npm - @gfargo/doorman - Versions diffs - 3.9.2 → 3.10.1 - Mend

@gfargo/doorman 3.9.2 → 3.10.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (8) hide show

package/dist/bin/run.js +89 -88
package/dist/bin/run.mjs +89 -88
package/package.json +1 -1
package/skills/doorman/SKILL.md +19 -16
package/skills/doorman/references/cicd.md +11 -9
package/skills/doorman/references/cloudflare.md +42 -44
package/skills/doorman/references/fastly.md +169 -0
package/skills/doorman/sync/plugin.json +2 -1

package/package.json CHANGED Viewed

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

package/skills/doorman/SKILL.md CHANGED Viewed

@@ -1,18 +1,18 @@
 ---
 name: doorman
-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.
+description: Manage Vercel, Cloudflare, and Fastly 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 provider 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.
+compatibility: Node.js >= 20. Requires provider API tokens (VERCEL_TOKEN, CLOUDFLARE_API_TOKEN, or FASTLY_API_TOKEN). Install globally via npm install -g @gfargo/doorman.
 metadata:
   author: gfargo
-  version: "1.0"
+  version: '1.0'
   homepage: https://github.com/gfargo/doorman
-  npm: "@gfargo/doorman"
+  npm: '@gfargo/doorman'
 ---
 # Doorman — Firewall Rules as Code
-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.
+Doorman is a CLI for managing WAF (Web Application Firewall) rules as code across Vercel, Cloudflare, and Fastly Next-Gen WAF. Configuration lives in `.doorman.json`, syncs bidirectionally with provider APIs, and integrates into CI/CD pipelines.
 ## Command Quick Reference
@@ -44,7 +44,7 @@ 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>`.
+All commands accept `--provider vercel|cloudflare|fastly` and `--config <path>`.
 ## Environment Variables
@@ -58,6 +58,10 @@ VERCEL_TEAM_ID=team_xxx
 CLOUDFLARE_API_TOKEN=your_token
 CLOUDFLARE_ZONE_ID=zone_xxx
 CLOUDFLARE_ACCOUNT_ID=acc_xxx   # optional, enables Lists API for bulk IP management
+# Fastly Next-Gen WAF (beta)
+FASTLY_API_TOKEN=your_token
+FASTLY_WORKSPACE_ID=workspace_xxx
 ```
 ## Config Structure
@@ -72,7 +76,7 @@ CLOUDFLARE_ACCOUNT_ID=acc_xxx   # optional, enables Lists API for bulk IP manage
 }
 ```
-For Cloudflare, add `provider` and `providers` fields instead of `projectId`/`teamId`.
+For Cloudflare or Fastly, add `provider` and `providers` fields instead of `projectId`/`teamId`.
 ## Core Workflow
@@ -93,9 +97,7 @@ doorman backup && doorman validate && doorman diff && doorman sync && doorman st
 {
   "name": "Block Admin",
   "active": true,
-  "conditionGroup": [
-    { "conditions": [{ "type": "path", "op": "pre", "value": "/admin" }] }
-  ],
+  "conditionGroup": [{ "conditions": [{ "type": "path", "op": "pre", "value": "/admin" }] }],
   "action": { "mitigate": { "action": "deny" } }
 }
 ```
@@ -112,12 +114,13 @@ doorman backup && doorman validate && doorman diff && doorman sync && doorman st
 Load the relevant reference file for detailed documentation:
-| 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) |
+| 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) |
+| Fastly-specific setup, condition/action mapping, rate-limit signal requirement, limitations | [references/fastly.md](references/fastly.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)             |
 ## Principles

package/skills/doorman/references/cicd.md CHANGED Viewed

@@ -170,6 +170,7 @@ doorman status --format json
 ```
 The health score evaluates:
 - Rule descriptions present
 - ID conventions followed (`rule_` prefix)
 - Operator complexity (penalizes unnecessary regex)
@@ -202,25 +203,26 @@ doorman sync --provider cloudflare --config .doorman.json
 ```bash
 # Migrate rules between providers
 doorman download --provider vercel --config .doorman.json
-doorman validate --provider cloudflare --config .doorman.json
+doorman validate --config .doorman.json
 doorman sync --provider cloudflare --config .doorman.json
 ```
 ## Command Flags Reference
-Global flags available on all commands:
+Common flags (availability varies by command):
-| 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 |
+| Flag                                              | Description                                                                                           |
+| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| `--config <path>`                                 | Path to config file (default: auto-discovered `.doorman.json`)                                        |
+| `--provider vercel\|cloudflare\|fastly`           | Override provider detection — `sync`/`diff`/`download`/`list`/`status`/`watch`/`backup`/`export` only |
+| `--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)

package/skills/doorman/references/cloudflare.md CHANGED Viewed

@@ -15,6 +15,7 @@ CLOUDFLARE_ACCOUNT_ID=acc_xxx      # Optional — enables Lists API for bulk IP
 ### 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`)
@@ -37,13 +38,14 @@ Multi-provider config with explicit provider declaration:
 }
 ```
-Or pass `--provider cloudflare` to any command to override the default.
+Or pass `--provider cloudflare` to any provider-aware command (`sync`, `diff`, `download`, `list`, `status`, `watch`, `backup`, `export`) to override auto-detection.
 ## Usage
+`doorman init` only supports Vercel today — it has no `--provider` flag and doesn't prompt for Cloudflare credentials. Create `.doorman.json` by hand using the config shape above, then:
 ```bash
-doorman init --provider cloudflare          # Initialize Cloudflare config
-doorman validate --provider cloudflare      # Validate against Cloudflare constraints
+doorman validate                            # Validate — auto-detects Cloudflare from the config's `provider` field
 doorman sync --provider cloudflare          # Deploy to Cloudflare
 doorman download --provider cloudflare      # Pull rules from Cloudflare
 doorman diff --provider cloudflare          # Compare local vs live
@@ -56,33 +58,33 @@ Doorman translates its unified rule format into Cloudflare Wirefilter expression
 ### 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) |
+| 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` |
+| 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)
@@ -97,16 +99,16 @@ Without `CLOUDFLARE_ACCOUNT_ID`, IP blocking falls back to individual WAF rules
 ## 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 |
+| 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
@@ -117,7 +119,7 @@ The `RuleTranslator` surfaces warnings when a translation is lossy:
 - **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.
+Run `doorman validate` to surface warnings before deploying — it auto-detects Cloudflare from the config's `provider` field.
 ## Cloudflare-Specific Validation
@@ -166,9 +168,7 @@ The `CloudflareOptimizer` consolidates rules for efficient deployment:
       "name": "Rate Limit API",
       "description": "Limit API requests to 100/min per IP",
       "active": true,
-      "conditionGroup": [
-        { "conditions": [{ "type": "path", "op": "pre", "value": "/api/" }] }
-      ],
+      "conditionGroup": [{ "conditions": [{ "type": "path", "op": "pre", "value": "/api/" }] }],
       "action": {
         "mitigate": {
           "action": "rate_limit",
@@ -181,8 +181,6 @@ The `CloudflareOptimizer` consolidates rules for efficient deployment:
       }
     }
   ],
-  "ips": [
-    { "ip": "203.0.113.0/24", "action": "deny", "notes": "Known attack subnet" }
-  ]
+  "ips": [{ "ip": "203.0.113.0/24", "action": "deny", "notes": "Known attack subnet" }]
 }
 ```

package/skills/doorman/references/fastly.md ADDED Viewed

@@ -0,0 +1,169 @@
+# Fastly Next-Gen WAF Provider Reference
+Fastly Next-Gen WAF support in Doorman (beta). Manage Next-Gen WAF (formerly Signal Sciences) workspace rules through the same config-as-code workflow. Classic Fastly VCL services are **not** supported — only the Next-Gen WAF's structured rules API.
+## Setup
+### Environment Variables
+```bash
+FASTLY_API_TOKEN=your_token        # Required — Fastly API token
+FASTLY_WORKSPACE_ID=workspace_xxx  # Required — Next-Gen WAF workspace to manage rules for
+```
+### API Token Permissions
+Create a token at https://manage.fastly.com/account/personal/tokens with access to the Next-Gen WAF product for the target workspace.
+### Config Shape
+Multi-provider config with explicit provider declaration:
+```json
+{
+  "$schema": "https://doorman.griffen.codes/schema.json",
+  "provider": "fastly",
+  "providers": {
+    "fastly": {
+      "workspaceId": "your_workspace_id"
+    }
+  },
+  "rules": [],
+  "ips": []
+}
+```
+Or pass `--provider fastly` to any provider-aware command (`sync`, `diff`, `download`, `list`, `status`, `watch`, `backup`, `export`) to override auto-detection.
+## Usage
+`doorman init` only supports Vercel today — it has no `--provider` flag and doesn't prompt for Fastly credentials. Create `.doorman.json` by hand using the config shape above, then:
+```bash
+doorman validate                        # Validate — auto-detects Fastly from the config's `provider` field
+doorman sync --provider fastly          # Deploy to Fastly
+doorman download --provider fastly      # Pull rules from Fastly
+doorman diff --provider fastly          # Compare local vs live
+doorman list --provider fastly          # Show deployed rules
+```
+## Rule Translation
+Doorman translates its unified rule format into Fastly's structured `request`-type rules automatically. The translation is bidirectional — `doorman download` pulls Fastly rules back into the unified format.
+### Field Mapping
+| Doorman Field | Fastly Condition           | Notes                                                   |
+| ------------- | -------------------------- | ------------------------------------------------------- |
+| `path`        | `path`                     |                                                         |
+| `method`      | `method`                   |                                                         |
+| `host`        | `domain`                   |                                                         |
+| `user_agent`  | `user_agent`               |                                                         |
+| `ip`          | `ip`                       |                                                         |
+| `country`     | `country`                  | Country-level only — no region/city/continent condition |
+| `scheme`      | `scheme`                   |                                                         |
+| `header`      | `request_header` multival  | Requires `key` (the header name)                        |
+| `query`       | `query_parameter` multival | Requires `key` (the parameter name)                     |
+| `cookie`      | `request_cookie` multival  | Requires `key` (the cookie name)                        |
+Fields with no Fastly equivalent (`region`, `city`, `asn`, `referer`, `port`, `target_path`, `environment`, `ja3_digest`, `ja4_digest`) are dropped with a translation warning rather than silently mistranslated — the rule still syncs with its remaining conditions.
+### Operator Mapping
+| Doorman Operator           | Fastly Operator                             | Notes                                                          |
+| -------------------------- | ------------------------------------------- | -------------------------------------------------------------- |
+| `eq`                       | `equals` (or `does_not_equal` if `negated`) |                                                                |
+| `contains`                 | `contains` (or `does_not_contain`)          |                                                                |
+| `matches`                  | `matches` (or `does_not_match`)             | Regex syntax may need adjustment                               |
+| `starts_with`, `ends_with` | `like` (or `not_like`)                      | Fastly's wildcard matching isn't a true prefix/suffix operator |
+| `in`                       | `in_list` (or `not_in_list`)                |                                                                |
+| `gt`, `lt`                 | `greater_equal`, `lesser_equal`             | No strict `>`/`<` on Fastly — boundary value also matches      |
+### Action Mapping
+| Doorman Action  | Fastly Action                                   | Notes                                                                                          |
+| --------------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| `block`, `deny` | `block`                                         |                                                                                                |
+| `allow`         | `allow`                                         |                                                                                                |
+| `challenge`     | `browser_challenge`                             |                                                                                                |
+| `redirect`      | `redirect`                                      | Uses `redirect_url` + `response_code`                                                          |
+| `rate_limit`    | Rule `type: rate_limit` + `block_signal` action | See Rate Limiting below                                                                        |
+| `log`           | `allow` (with a warning)                        | Fastly has no dedicated log-only action; `request_logging` is set at the rule level regardless |
+| `bypass`        | `allow` (with a warning)                        | No equivalent action                                                                           |
+## Condition Grouping
+Fastly's condition model is bounded to two levels — a rule's top-level conditions can be plain, or grouped, but a group's own members can never contain another group. This matches Doorman's flat `group` model exactly:
+- Conditions sharing a `group` index are AND'd together.
+- Distinct `group` values are OR'd against each other.
+- A single implicit group (the common case) becomes flat top-level conditions.
+## Rate Limiting
+Fastly rate-limit rules are a distinct rule type (`type: "rate_limit"`) with their own `rate_limit` block (`threshold`, `interval`, `duration`, a counting `signal`). Doorman's `window` (e.g. `"60s"`, `"5m"`) is rounded to the nearest interval Fastly supports (60s / 600s / 3600s).
+**Fastly rate-limit rules count requests against a named custom signal that must already exist in the workspace** — Doorman does not create it automatically. Create a signal named `doorman-rate-limit-<rule-id>` before syncing a rate-limit rule, or the sync will be rejected. A translation warning is emitted every time to make this easy to miss less easily.
+## IP Blocking
+Fastly has no per-IP-rule resource — Doorman manages two workspace **lists** of type `ip` (`doorman-managed-deny`, `doorman-managed-allow`), each replaced wholesale on sync (the same atomic-replace shape as Cloudflare's ruleset write, not Vercel's per-item writes). `hostname`/`notes` on an IP rule have no Fastly equivalent and are dropped with a warning — only the address is kept.
+## No Draft/Publish Step
+Unlike classic Fastly VCL services, Next-Gen WAF rule and list writes take effect immediately — there is no draft-then-activate version to manage. A rule's `enabled` flag is the only gate on whether it's live.
+## Limitations & Differences
+| Feature                    | Vercel                        | Fastly                 | Notes                                                                     |
+| -------------------------- | ----------------------------- | ---------------------- | ------------------------------------------------------------------------- |
+| Geo targeting              | Country/city/continent/region | Country only           | No sub-country condition field                                            |
+| Rule ordering              | Best-effort (insertion order) | None                   | Next-Gen WAF rules are evaluated independently — `priority` has no effect |
+| Managed/vendor rule groups | CRS (enterprise)              | Templated signal rules | Not yet configurable through Doorman for either provider (#183)           |
+| Signal/exclusion rules     | —                             | `type: signal`         | Not managed by Doorman — see below                                        |
+Fastly rules of type `signal` or `templated_signal` (which tag or exclude WAF signals rather than allow/block/redirect a request) are skipped entirely by `doorman download`/`fetchConfig` rather than forced into a lossy `UnifiedRule` — they simply don't appear in the local config.
+## Example: Full Fastly Config
+```json
+{
+  "$schema": "https://doorman.griffen.codes/schema.json",
+  "provider": "fastly",
+  "providers": {
+    "fastly": {
+      "workspaceId": "abc123def456"
+    }
+  },
+  "rules": [
+    {
+      "id": "rule_block_bots",
+      "name": "Block Bad Bots",
+      "enabled": true,
+      "conditions": [
+        { "field": "user_agent", "operator": "contains", "value": "AhrefsBot", "group": 0 },
+        { "field": "user_agent", "operator": "contains", "value": "SemrushBot", "group": 1 }
+      ],
+      "action": { "type": "block" }
+    },
+    {
+      "id": "rule_admin_header",
+      "name": "Require internal header on admin paths",
+      "enabled": true,
+      "conditions": [
+        { "field": "path", "operator": "starts_with", "value": "/admin", "group": 0 },
+        {
+          "field": "header",
+          "operator": "eq",
+          "value": "internal",
+          "key": "X-Access-Level",
+          "negated": true,
+          "group": 0
+        }
+      ],
+      "action": { "type": "block" }
+    }
+  ],
+  "ips": [{ "ip": "203.0.113.0/24", "action": "deny" }]
+}
+```

package/skills/doorman/sync/plugin.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "security",
-  "description": "Web application firewall management as code with Doorman: create rules, block IPs, rate limit, protect against bots, and deploy WAF configs to Vercel and Cloudflare.",
+  "description": "Web application firewall management as code with Doorman: create rules, block IPs, rate limit, protect against bots, and deploy WAF configs to Vercel, Cloudflare, and Fastly.",
   "version": "1.0.0",
   "author": {
     "name": "Griffen Fargo",
@@ -13,6 +13,7 @@
     "waf",
     "vercel",
     "cloudflare",
+    "fastly",
     "doorman",
     "iac",
     "rules",