@gfargo/doorman 3.1.0 → 3.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gfargo/doorman",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "description": "Manage firewall rules as code across multiple providers",
   "publishConfig": {
     "access": "public"

package/skills/doorman/.source-version

@@ -0,0 +1 @@
+v3.1.0

package/skills/doorman/SKILL.md

@@ -1,33 +1,47 @@
 ---
 name: doorman
-description: 'Use when managing Vercel or Cloudflare WAF rules as code, configuring firewall rules, IP blocking, rate limiting, bot protection, or automating multi-provider security configuration deployment with Doorman CLI.'
+description: Manage Vercel and Cloudflare WAF firewall rules as code with the Doorman CLI. Use for any firewall-as-code task — creating rules, IP blocking, rate limiting, bot protection, geo-blocking, syncing local config to providers, validating configurations, exporting documentation, CI/CD automation, or translating rules between Vercel and Cloudflare formats.
+license: MIT
+compatibility: Node.js >= 20. Requires provider API tokens (VERCEL_TOKEN or CLOUDFLARE_API_TOKEN). Install globally via npm install -g @gfargo/doorman.
+metadata:
+  author: gfargo
+  version: "1.0"
+  homepage: https://github.com/gfargo/doorman
+  npm: "@gfargo/doorman"
 ---
 
-# Doorman
+# Doorman — Firewall Rules as Code
 
-Multi-provider WAF automation as code. Manage Vercel Firewall and Cloudflare WAF rules in version-controlled `.doorman.json` files with automated deployment via CLI.
+Doorman is a CLI for managing WAF (Web Application Firewall) rules as code across Vercel and Cloudflare. Configuration lives in `.doorman.json`, syncs bidirectionally with provider APIs, and integrates into CI/CD pipelines.
 
-## Key Concepts
-
-- **Config file**: `.doorman.json` (also supports legacy `vercel-firewall.config.json`)
-- **Providers**: Vercel (default) and Cloudflare (`--provider cloudflare`)
-- **Workflow**: Edit config → validate → diff → sync
-- **Schema**: `https://doorman.griffen.codes/schema.json`
-
-## Commands
+## Command Quick Reference
 
 ```bash
-doorman init --interactive       # Create new config
-doorman validate                 # Check config syntax
-doorman status                   # Sync status + health score
-doorman list                     # Show deployed rules
-doorman diff                     # Local vs remote differences
-doorman sync                     # Deploy local config to provider
-doorman download                 # Pull remote rules to local config
-doorman template <name>          # Add pre-built rule template
-doorman watch                    # Auto-sync on file changes
-doorman backup                   # Create config backup
-doorman export --format <fmt>    # Export as markdown|json|yaml|terraform
+# Setup & Init
+doorman setup                       # Show setup guide with links
+doorman init --interactive          # Create new config interactively
+doorman init security-focused       # Start with security templates
+
+# Rule Creation
+doorman add --interactive           # Guided rule creation
+doorman add --name "Block" --field path --op pre --value "/admin" --action deny
+doorman template ai-bots            # Add pre-built template
+
+# Status & Inspection
+doorman status                      # Sync status + health score
+doorman list                        # Show deployed rules (table/json)
+doorman diff                        # Local vs remote differences
+
+# Sync & Deploy
+doorman validate                    # Check config syntax + health
+doorman sync                        # Deploy local config to provider
+doorman download                    # Pull remote rules to local config
+
+# Advanced
+doorman watch                       # Auto-sync on file changes
+doorman backup                      # Create/restore config backups
+doorman export --format markdown    # Export as markdown|json|yaml|terraform
+doorman remove --name "Old Rule"    # Remove rules by name/ID
 ```
 
 All commands accept `--provider vercel|cloudflare` and `--config <path>`.
@@ -35,15 +49,15 @@ All commands accept `--provider vercel|cloudflare` and `--config <path>`.
 ## Environment Variables
 
 ```bash
-# Vercel
+# Vercel (default provider)
 VERCEL_TOKEN=your_token
 VERCEL_PROJECT_ID=prj_xxx
 VERCEL_TEAM_ID=team_xxx
 
-# Cloudflare
+# Cloudflare (beta)
 CLOUDFLARE_API_TOKEN=your_token
 CLOUDFLARE_ZONE_ID=zone_xxx
-CLOUDFLARE_ACCOUNT_ID=acc_xxx  # optional, enables Lists API
+CLOUDFLARE_ACCOUNT_ID=acc_xxx   # optional, enables Lists API for bulk IP management
 ```
 
 ## Config Structure
@@ -58,75 +72,58 @@ CLOUDFLARE_ACCOUNT_ID=acc_xxx  # optional, enables Lists API
 }
 ```
 
-For Cloudflare, use `provider` and `providers` fields instead of `projectId`/`teamId`.
+For Cloudflare, add `provider` and `providers` fields instead of `projectId`/`teamId`.
+
+## Core Workflow
+
+```bash
+# Edit .doorman.json (add/modify rules), then:
+doorman validate && doorman diff && doorman sync
+
+# Pull existing rules from a live provider:
+doorman download
+
+# Safe production deployment:
+doorman backup && doorman validate && doorman diff && doorman sync && doorman status
+```
 
-## Rule Quick Reference
+## Rule Shape (Minimal)
 
 ```json
 {
-  "id": "rule_block_admin",
-  "name": "Block Admin Access",
-  "description": "Block unauthorized admin access",
+  "name": "Block Admin",
   "active": true,
   "conditionGroup": [
-    {
-      "conditions": [
-        { "type": "path", "op": "pre", "value": "/admin" },
-        { "type": "method", "op": "eq", "value": "POST" }
-      ]
-    }
+    { "conditions": [{ "type": "path", "op": "pre", "value": "/admin" }] }
   ],
-  "action": {
-    "mitigate": {
-      "action": "deny"
-    }
-  }
+  "action": { "mitigate": { "action": "deny" } }
 }
 ```
 
 **Logic**: Conditions within a group are AND'd. Multiple groups are OR'd.
 
-**Condition types**: `path`, `method`, `host`, `user_agent`, `ip_address`, `header`, `query`, `cookie`, `geo_country`, `geo_city`, `geo_continent`, `scheme`
+**Condition types**: `path`, `method`, `host`, `user_agent`, `ip_address`, `header`, `query`, `cookie`, `geo_country`, `geo_city`, `geo_continent`, `geo_country_region`, `geo_as_number`, `scheme`, `protocol`
 
-**Operators**: `eq`, `pre` (starts_with), `suf` (ends_with), `sub` (contains), `inc` (in array), `re` (regex), `ex` (exists), `nex` (not exists)
+**Operators**: `eq`, `pre` (prefix), `suf` (suffix), `sub` (contains), `inc` (in array), `re` (regex), `ex` (exists), `nex` (not exists)
 
 **Actions**: `deny`, `challenge`, `rate_limit`, `redirect`, `log`, `bypass`
 
-**See `rules-reference.md` for complete field documentation, advanced patterns, and examples.**
-
-## IP Blocking
-
-```json
-{
-  "ips": [{ "ip": "192.168.1.0/24", "action": "deny", "hostname": "bad-subnet", "notes": "Blocked for abuse" }]
-}
-```
-
-## Templates
-
-```bash
-doorman template bad-bots       # Block malicious bots
-doorman template ai-bots        # Block AI crawlers
-doorman template wordpress      # Block WordPress attack paths
-doorman template block-ofac-sanctioned-countries  # OFAC compliance
-```
-
-## Workflow
-
-```bash
-# Add a rule: edit .doorman.json, then:
-doorman validate && doorman sync
+## When to Read Each Reference
 
-# Pull existing rules from provider:
-doorman download
+Load the relevant reference file for detailed documentation:
 
-# Check what would change before deploying:
-doorman diff
-```
+| Task | Reference |
+|------|-----------|
+| Writing rules — full field docs, operators, actions, IP blocking, patterns | [references/rules.md](references/rules.md) |
+| Cloudflare-specific setup, Lists API, expression translation, limitations | [references/cloudflare.md](references/cloudflare.md) |
+| Available templates and what they protect against | [references/templates.md](references/templates.md) |
+| CI/CD integration, automation, export formats, validation in pipelines | [references/cicd.md](references/cicd.md) |
 
-## Resources
+## Principles
 
-- [Docs](https://doorman.griffen.codes/docs)
-- [GitHub](https://github.com/gfargo/doorman)
-- [Wiki](https://github.com/gfargo/doorman/wiki)
-- [Examples](https://github.com/gfargo/doorman/tree/main/examples)
+1. **Validate before syncing** — always run `doorman validate` before `doorman sync`.
+2. **Diff before deploying** — use `doorman diff` to preview what will change on the provider.
+3. **Backup before major changes** — `doorman backup` creates a timestamped snapshot.
+4. **Config is the source of truth** — make changes in `.doorman.json`, let sync propagate them.
+5. **Use templates for common patterns** — `doorman template` has battle-tested rules for bots, geo-blocking, and attack paths.
+6. **Health score matters** — add descriptions, use IDs with `rule_` prefix, avoid regex when simpler operators work.

package/skills/doorman/references/cicd.md

@@ -0,0 +1,240 @@
+# CI/CD & Automation Reference
+
+Integrating Doorman into automated pipelines, export formats, and programmatic usage.
+
+## CI/CD Pipeline Integration
+
+Doorman commands return structured output and meaningful exit codes for automation.
+
+### Validation in CI
+
+```bash
+# Fail the build if config is invalid
+doorman validate --config .doorman.json
+# Exit 0 = valid, Exit 1 = validation errors
+```
+
+### Diff Check (Detect Changes)
+
+```bash
+# Check if local config differs from deployed
+doorman diff --format json --config .doorman.json
+# Exit 0 = differences found (outputs JSON), Exit 1 = error
+```
+
+### Automated Sync
+
+```bash
+# Deploy rules non-interactively
+doorman sync --config .doorman.json
+```
+
+### Full Pipeline Example (GitHub Actions)
+
+```yaml
+name: Deploy Firewall Rules
+on:
+  push:
+    branches: [main]
+    paths: ['.doorman.json']
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - run: npm install -g @gfargo/doorman
+
+      - name: Validate
+        run: doorman validate --config .doorman.json
+
+      - name: Preview Changes
+        run: doorman diff --format json --config .doorman.json || true
+
+      - name: Deploy
+        run: doorman sync --config .doorman.json
+        env:
+          VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}
+          VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}
+          VERCEL_TEAM_ID: ${{ secrets.VERCEL_TEAM_ID }}
+```
+
+### Cloudflare Pipeline
+
+```yaml
+- name: Deploy to Cloudflare
+  run: doorman sync --provider cloudflare --config .doorman.json
+  env:
+    CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+    CLOUDFLARE_ZONE_ID: ${{ secrets.CLOUDFLARE_ZONE_ID }}
+    CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+```
+
+## Export Formats
+
+```bash
+doorman export --format json                    # JSON (default)
+doorman export --format yaml                    # YAML
+doorman export --format markdown                # Human-readable Markdown
+doorman export --format terraform               # Terraform HCL
+doorman export --output firewall-docs.md        # Write to file
+```
+
+### JSON Export
+
+Full config dump, useful for backup or diffing:
+
+```bash
+doorman export --format json > firewall-backup.json
+```
+
+### YAML Export
+
+Human-friendly format for documentation:
+
+```bash
+doorman export --format yaml --output firewall.yaml
+```
+
+### Markdown Export
+
+Generate team-readable documentation:
+
+```bash
+doorman export --format markdown --output FIREWALL.md
+```
+
+Produces a table of all rules with their conditions, actions, and status.
+
+### Terraform Export
+
+Generate Terraform HCL for infrastructure-as-code repositories:
+
+```bash
+doorman export --format terraform --output firewall.tf
+```
+
+## Backup & Restore
+
+```bash
+# Create a timestamped backup
+doorman backup
+
+# List all backups
+doorman backup --list
+
+# Restore from a backup
+doorman backup --restore <filename>
+```
+
+Backups are stored locally as JSON files. Include backup creation in your deployment pipeline as a safety net.
+
+## Watch Mode (Development)
+
+```bash
+# Auto-validate and sync on file changes
+doorman watch
+
+# Watch a specific config
+doorman watch --config .doorman.json
+```
+
+Watch mode is for development only — it syncs immediately on save. Do not use in production pipelines.
+
+## Programmatic Usage (Node.js)
+
+Doorman can be used as a library in Node.js applications:
+
+```typescript
+import { createDoorman } from '@gfargo/doorman/next'
+
+// Next.js middleware integration
+const doorman = createDoorman({
+  // Configuration options
+})
+```
+
+## Status & Health Monitoring
+
+```bash
+# Check sync status and configuration health
+doorman status
+
+# Machine-readable status
+doorman status --format json
+```
+
+The health score evaluates:
+- Rule descriptions present
+- ID conventions followed (`rule_` prefix)
+- Operator complexity (penalizes unnecessary regex)
+- Active/inactive rule ratio
+- Bot protection coverage
+- Rate limiting coverage
+
+## Multi-Environment Strategies
+
+### Separate configs per environment
+
+```bash
+# Production
+doorman sync --config .doorman.prod.json
+
+# Staging (lighter rules)
+doorman sync --config .doorman.staging.json
+```
+
+### Single config, different providers
+
+```bash
+# Same rules, different targets
+doorman sync --provider vercel --config .doorman.json
+doorman sync --provider cloudflare --config .doorman.json
+```
+
+### Download from one, deploy to another
+
+```bash
+# Migrate rules between providers
+doorman download --provider vercel --config .doorman.json
+doorman validate --provider cloudflare --config .doorman.json
+doorman sync --provider cloudflare --config .doorman.json
+```
+
+## Command Flags Reference
+
+Global flags available on all commands:
+
+| Flag | Description |
+|------|-------------|
+| `--config <path>` | Path to config file (default: auto-discovered `.doorman.json`) |
+| `--provider vercel\|cloudflare` | Override provider detection |
+| `--format json\|table\|yaml\|markdown\|terraform` | Output format (command-dependent) |
+| `--verbose` | Show detailed output |
+| `--output <path>` | Write output to file instead of stdout |
+
+## Error Handling in Automation
+
+Doorman exit codes:
+- `0` — success
+- `1` — error (validation failure, API error, config not found)
+
+Errors are written to stderr in a structured format. In CI, capture stderr for diagnostics:
+
+```bash
+doorman sync 2> sync-errors.log || { cat sync-errors.log; exit 1; }
+```
+
+## Security Best Practices for CI/CD
+
+1. **Never commit tokens** — use CI secrets/environment variables exclusively
+2. **Validate before deploy** — always run `doorman validate` as a gate before `doorman sync`
+3. **Use `doorman diff`** — review changes in PR checks before merge triggers deployment
+4. **Backup before sync** — automate `doorman backup` before every `doorman sync` in production
+5. **Pin the doorman version** — use `npm install -g @gfargo/doorman@3.x` to avoid unexpected breaking changes
+6. **Limit token scope** — use the narrowest API token permissions possible (project-scoped for Vercel, zone-scoped for Cloudflare)

package/skills/doorman/references/cloudflare.md

@@ -0,0 +1,188 @@
+# Cloudflare Provider Reference
+
+Cloudflare WAF support in Doorman (beta). Manage Cloudflare custom rulesets and IP Lists through the same config-as-code workflow.
+
+## Setup
+
+### Environment Variables
+
+```bash
+CLOUDFLARE_API_TOKEN=your_token    # Required — API token with Zone.Firewall permissions
+CLOUDFLARE_ZONE_ID=zone_xxx        # Required — zone to manage rules for
+CLOUDFLARE_ACCOUNT_ID=acc_xxx      # Optional — enables Lists API for bulk IP management
+```
+
+### API Token Permissions
+
+Create a Custom Token at https://dash.cloudflare.com/profile/api-tokens with:
+- **Zone > Firewall Services > Edit** — for custom rulesets
+- **Account > Account Filter Lists > Edit** — for Lists API (bulk IP management, requires `CLOUDFLARE_ACCOUNT_ID`)
+
+### Config Shape
+
+Multi-provider config with explicit provider declaration:
+
+```json
+{
+  "$schema": "https://doorman.griffen.codes/schema.json",
+  "provider": "cloudflare",
+  "providers": {
+    "cloudflare": {
+      "zoneId": "your_zone_id",
+      "accountId": "your_account_id"
+    }
+  },
+  "rules": [],
+  "ips": []
+}
+```
+
+Or pass `--provider cloudflare` to any command to override the default.
+
+## Usage
+
+```bash
+doorman init --provider cloudflare          # Initialize Cloudflare config
+doorman validate --provider cloudflare      # Validate against Cloudflare constraints
+doorman sync --provider cloudflare          # Deploy to Cloudflare
+doorman download --provider cloudflare      # Pull rules from Cloudflare
+doorman diff --provider cloudflare          # Compare local vs live
+doorman list --provider cloudflare          # Show deployed rules
+```
+
+## Rule Translation
+
+Doorman translates its unified rule format into Cloudflare Wirefilter expressions automatically. The translation is bidirectional — `doorman download` pulls Cloudflare expressions back into the unified format.
+
+### Field Mapping
+
+| Doorman Type | Cloudflare Field |
+|-------------|------------------|
+| `path` | `http.request.uri.path` |
+| `method` | `http.request.method` |
+| `host` | `http.host` |
+| `user_agent` | `http.user_agent` |
+| `ip_address` | `ip.src` |
+| `header` | `http.request.headers["key"]` |
+| `query` | `http.request.uri.query` |
+| `cookie` | `http.cookie` |
+| `geo_country` | `ip.geoip.country` |
+| `geo_city` | `ip.geoip.city` |
+| `geo_continent` | `ip.geoip.continent` |
+| `geo_country_region` | `ip.geoip.subdivision_1` |
+| `geo_as_number` | `ip.geoip.asnum` |
+| `scheme` | `ssl` (boolean) |
+
+### Action Mapping
+
+| Doorman Action | Cloudflare Action |
+|---------------|-------------------|
+| `deny` | `block` |
+| `challenge` | `managed_challenge` |
+| `rate_limit` | `block` + `ratelimit` config |
+| `redirect` | `redirect` + `from_value` params |
+| `log` | `log` |
+| `bypass` | `skip` |
+
+## Lists API (Bulk IP Management)
+
+When `CLOUDFLARE_ACCOUNT_ID` is set, IP rules in the `ips` array are managed via Cloudflare's Lists API — a dedicated service for bulk IP blocking that scales better than individual rules.
+
+```bash
+# IPs in config are synced to a Cloudflare List
+doorman sync --provider cloudflare
+```
+
+Without `CLOUDFLARE_ACCOUNT_ID`, IP blocking falls back to individual WAF rules with `ip.src` expressions — functional but limited by rule count quotas.
+
+## Limitations & Differences
+
+| Feature | Vercel | Cloudflare | Notes |
+|---------|--------|------------|-------|
+| `re` operator | All plans | Enterprise only | Use `sub`/`pre`/`suf` as alternatives |
+| `environment` type | Yes | No | Vercel-specific concept |
+| `ja3_digest`/`ja4_digest` | Yes | No | Vercel TLS fingerprints |
+| `region` type | Yes | No | Vercel edge region |
+| IP Lists (bulk) | Individual rules | Lists API | Cloudflare needs `accountId` |
+| Max custom rules | ~100 | 5-125 (plan dependent) | Free: 5, Pro: 20, Business: 100, Enterprise: 125+ |
+| Rate limit | Via rule action | Separate phase | Different underlying mechanism |
+| Rule order | Parallel evaluation | Sequential (first match wins) | Ordering matters on Cloudflare |
+
+## Translation Warnings
+
+The `RuleTranslator` surfaces warnings when a translation is lossy:
+
+- **Regex on non-Enterprise** — `re` operator only works on Cloudflare Enterprise; downgraded to `contains` with a warning
+- **Unsupported types** — Vercel-only fields (`environment`, `ja3_digest`, `ja4_digest`, `region`) are dropped with a warning
+- **Duration differences** — `actionDuration` maps differently between providers
+- **Negation edge cases** — complex negated conditions may produce subtly different behavior in Wirefilter
+
+Run `doorman validate --provider cloudflare` to surface warnings before deploying.
+
+## Cloudflare-Specific Validation
+
+Doorman validates Cloudflare configs against:
+
+- Expression syntax (Wirefilter grammar)
+- Rule count limits per plan
+- Action compatibility (e.g., `js_challenge` deprecated in favor of `managed_challenge`)
+- List reference validity (when using Lists API)
+- Rate limit configuration completeness
+
+## Optimizer
+
+The `CloudflareOptimizer` consolidates rules for efficient deployment:
+
+- Merges rules with identical actions into single expressions using `or`
+- Deduplicates IP entries across rules and Lists
+- Computes minimal changesets to avoid unnecessary API calls (diff-based sync)
+
+## Example: Full Cloudflare Config
+
+```json
+{
+  "$schema": "https://doorman.griffen.codes/schema.json",
+  "provider": "cloudflare",
+  "providers": {
+    "cloudflare": {
+      "zoneId": "abc123def456",
+      "accountId": "acc789xyz"
+    }
+  },
+  "rules": [
+    {
+      "id": "rule_block_bots",
+      "name": "Block Bad Bots",
+      "description": "Block known malicious crawlers",
+      "active": true,
+      "conditionGroup": [
+        { "conditions": [{ "type": "user_agent", "op": "sub", "value": "AhrefsBot" }] },
+        { "conditions": [{ "type": "user_agent", "op": "sub", "value": "SemrushBot" }] }
+      ],
+      "action": { "mitigate": { "action": "deny" } }
+    },
+    {
+      "id": "rule_rate_limit_api",
+      "name": "Rate Limit API",
+      "description": "Limit API requests to 100/min per IP",
+      "active": true,
+      "conditionGroup": [
+        { "conditions": [{ "type": "path", "op": "pre", "value": "/api/" }] }
+      ],
+      "action": {
+        "mitigate": {
+          "action": "rate_limit",
+          "rateLimit": {
+            "requests": 100,
+            "window": "1m",
+            "characteristics": ["ip.src"]
+          }
+        }
+      }
+    }
+  ],
+  "ips": [
+    { "ip": "203.0.113.0/24", "action": "deny", "notes": "Known attack subnet" }
+  ]
+}
+```