@jaypie/mcp 0.8.64 → 0.8.66

package/dist/suites/docs/index.js

@@ -9,7 +9,7 @@ import { gt } from 'semver';
 /**
  * Docs Suite - Documentation services (skill, version, release_notes)
  */
-const BUILD_VERSION_STRING = "@jaypie/mcp@0.8.64#0a1f765f"
+const BUILD_VERSION_STRING = "@jaypie/mcp@0.8.66#da12e12f"
     ;
 const __filename$1 = fileURLToPath(import.meta.url);
 const __dirname$1 = path.dirname(__filename$1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaypie/mcp",
-  "version": "0.8.64",
+  "version": "0.8.66",
   "description": "Jaypie MCP",
   "repository": {
     "type": "git",

package/release-notes/constructs/1.2.60.md

@@ -0,0 +1,24 @@
+---
+version: 1.2.60
+date: 2026-06-04
+summary: Validate WAF managedRuleOverrides/allow rule names at synth, throwing ConfigurationError on unknown names
+---
+
+## @jaypie/constructs 1.2.60
+
+### Fixed
+
+- **WAF rule-name validation** (`JaypieDistribution`, `JaypieWebDeploymentBucket`).
+  `waf.allow` and `waf.managedRuleOverrides` rule names are now validated against
+  each AWS managed rule group at synth time. AWS WAF matches `RuleActionOverride`
+  on the exact rule **name** and silently ignores any name that matches no rule —
+  so a typo, or the label/name casing trap (label
+  `…:core-rule-set:NoUserAgent_Header` vs rule name `NoUserAgent_HEADER`), used to
+  produce a WebACL that looked correct but kept blocking. Jaypie now throws a
+  `ConfigurationError` listing the valid rule names for the group. Custom
+  (non-AWS) rule groups are not validated.
+
+  New helper `assertValidWafRuleNames` and the canonical `AWS_MANAGED_RULE_GROUPS`
+  map are exported from the package.
+
+Issue: [#362](https://github.com/finlaysonstudio/jaypie/issues/362)

package/release-notes/mcp/0.8.65.md

@@ -0,0 +1,17 @@
+---
+version: 0.8.65
+date: 2026-06-04
+summary: Extract WAF guidance into a dedicated skill("waf") with allow prop and rule-name casing trap coverage
+---
+
+## Changed
+
+- **New `waf` skill**. WAF guidance moved out of `skill("cdk")` into a dedicated
+  `skill("waf")`, mirroring how `dns`, `secrets`, and `streaming` are split out.
+  `skill("cdk")` keeps a one-line **See Also → `skill("waf")`** pointer.
+- **`waf` skill** adds coverage of the `waf.allow` path-scoped relaxation prop
+  and the **rule name ≠ label casing trap** (label
+  `…:core-rule-set:NoUserAgent_Header` vs rule name `NoUserAgent_HEADER`), noting
+  that `@jaypie/constructs` now validates rule names at synth.
+
+Issue: [#362](https://github.com/finlaysonstudio/jaypie/issues/362)

package/release-notes/mcp/0.8.66.md

@@ -0,0 +1,14 @@
+---
+version: 0.8.66
+date: 2026-06-05
+summary: Document request envelope in skill("api") — requests use the same { data } object-vs-array rules as responses
+---
+
+## Changed
+
+- **`api` skill** now documents the **request envelope**. Request bodies follow
+  the same `{ data }` convention as responses: `{ data: {} }` for a single record
+  (object), `{ data: [] }` for an array of records. The request rule was
+  previously undocumented in every skill file — only response format was covered.
+- Retitled the skill to **API Request and Response Format** and added a request
+  rule to the shared rules list.

package/skills/agents.md

@@ -34,7 +34,7 @@ Complete stack styles, techniques, and traditions.
 
 Contents: index, releasenotes
 Development: apikey, documentation, errors, llm, logs, mocks, monorepo, repokit, style, subpackages, tests, tools
-Infrastructure: apigateway, aws, cdk, cicd, datadog, dns, dynamodb, express, lambda, migrations, secrets, sqs, streaming, variables, web, websockets
+Infrastructure: apigateway, aws, cdk, cicd, datadog, dns, dynamodb, express, lambda, migrations, secrets, sqs, streaming, variables, waf, web, websockets
 Patterns: api, fabric, handlers, models, services, vocabulary
 Recipes: recipe-api-server
 Meta: issues, jaypie, mcp, skills

package/skills/api.md

@@ -1,11 +1,27 @@
 ---
-description: API response format and conventions
+description: API request and response format and conventions
 related: express, handlers, style
 ---
 
-# API Response Format
+# API Request and Response Format
 
-All API responses follow a consistent envelope format.
+All API requests and responses follow a consistent envelope format.
+
+## Request Envelope
+
+Request bodies follow the same `{ data }` envelope as responses.
+
+```json
+// Single record
+{ "data": { "name": "Example" } }
+
+// Array of records
+{ "data": [{ "name": "First" }, { "name": "Second" }] }
+```
+
+- `{ data: {} }` — single record (object)
+- `{ data: [] }` — array of records (even if zero or one result)
+- No other top-level keys at the root
 
 ## Response Envelope
 
@@ -39,8 +55,9 @@ Every response body is a JSON object with one top-level key:
 
 ### Rules
 
-1. A response contains either `data` or `errors`, never both
-2. Single records use an object: `{ data: {} }`
-3. Multiple records use an array: `{ data: [] }`
-4. Errors always use an array: `{ errors: [] }`
-5. No other top-level keys (no `status`, `message`, `meta` at the root)
+1. Requests and responses both use the `{ data }` envelope
+2. A response contains either `data` or `errors`, never both
+3. Single records use an object: `{ data: {} }`
+4. Multiple records use an array: `{ data: [] }`
+5. Errors always use an array: `{ errors: [] }` (responses only)
+6. No other top-level keys (no `status`, `message`, `meta` at the root)

package/skills/cdk.md

@@ -1,6 +1,6 @@
 ---
 description: CDK constructs and deployment patterns
-related: apikey, aws, cicd, dynamodb, express, lambda, migrations, secrets, streaming, web, websockets
+related: apikey, aws, cicd, dynamodb, express, lambda, migrations, secrets, streaming, waf, web, websockets
 ---
 
 # CDK Constructs
@@ -347,89 +347,13 @@ new JaypieDistribution(this, "Dist", {
 
 ## WAF (Web Application Firewall)
 
-`JaypieDistribution` attaches a WAFv2 WebACL by default with:
+`JaypieDistribution` and `JaypieWebDeploymentBucket` attach a WAFv2 WebACL by
+default (CommonRuleSet, KnownBadInputsRuleSet, IP rate limiting, and WAF logging
+to S3 with Datadog forwarding).
 
-- **AWSManagedRulesCommonRuleSet** — OWASP top 10 (SQLi, XSS, etc.)
-- **AWSManagedRulesKnownBadInputsRuleSet** — known bad patterns (Log4j, etc.)
-- **Rate limiting** — 2000 requests per 5 minutes per IP
-- **WAF logging** — S3 bucket with Datadog forwarder notifications
-
-```typescript
-// Default: WAF enabled with logging
-new JaypieDistribution(this, "Dist", { handler });
-
-// Disable WAF entirely
-new JaypieDistribution(this, "Dist", { handler, waf: false });
-
-// Customize rate limit (name required on any waf config object)
-new JaypieDistribution(this, "Dist", {
-  handler,
-  waf: { name: "api", rateLimitPerIp: 500 },
-});
-
-// Multiple distributions in one env — set a unique waf.name on each to
-// avoid WebACL/S3 bucket name collisions between stacks.
-new JaypieDistribution(this, "Api", { handler: api, waf: { name: "api" } });
-new JaypieDistribution(this, "Mcp", { handler: mcp, waf: { name: "mcp" } });
-
-// Use existing WebACL
-new JaypieDistribution(this, "Dist", {
-  handler,
-  waf: { name: "api", webAclArn: "arn:aws:wafv2:..." },
-});
-
-// Disable WAF logging only
-new JaypieDistribution(this, "Dist", {
-  handler,
-  waf: { name: "api", logBucket: false },
-});
-
-// Bring your own WAF logging bucket
-new JaypieDistribution(this, "Dist", {
-  handler,
-  waf: { name: "api", logBucket: myWafBucket },
-});
-
-// Override specific managed rule actions (e.g., allow large request bodies)
-new JaypieDistribution(this, "Dist", {
-  handler,
-  waf: {
-    name: "api",
-    managedRuleOverrides: {
-      AWSManagedRulesCommonRuleSet: [
-        { name: "SizeRestrictions_BODY", actionToUse: { count: {} } },
-      ],
-    },
-  },
-});
-
-// Scope a managed rule group to (or away from) specific URL patterns
-new JaypieDistribution(this, "Dist", {
-  handler,
-  waf: {
-    name: "api",
-    managedRuleScopeDowns: {
-      // Only run the CommonRuleSet for paths OTHER than /chat — lets /chat
-      // handle large AI-generated request bodies without weakening protection
-      // elsewhere.
-      AWSManagedRulesCommonRuleSet: {
-        notStatement: {
-          statement: {
-            byteMatchStatement: {
-              fieldToMatch: { uriPath: {} },
-              positionalConstraint: "STARTS_WITH",
-              searchString: "/chat",
-              textTransformations: [{ priority: 0, type: "NONE" }],
-            },
-          },
-        },
-      },
-    },
-  },
-});
-```
-
-Cost: $5/month per WebACL + $1/month per rule + $0.60 per million requests. Use `waf: false` to opt out.
+See **`skill("waf")`** for configuration: `rateLimitPerIp`, `webAclArn`,
+`logBucket`, `managedRuleOverrides`, `managedRuleScopeDowns`, the `allow`
+path-scoped relaxation prop, and the rule-name ↔ label casing trap.
 
 ## Organization Trail Security Baseline
 
@@ -465,5 +389,6 @@ new JaypieOrganizationTrail(this, "OrgTrail", {
 - **`skill("secrets")`** - Secret management with JaypieEnvSecret
 - **`skill("streaming")`** - JaypieDistribution and JaypieNextJs streaming configuration
 - **`skill("variables")`** - Environment variables reference
+- **`skill("waf")`** - WAF configuration, managed rule overrides, and the `allow` prop
 - **`skill("web")`** - JaypieWebDeploymentBucket and JaypieStaticWebBucket for static sites
 - **`skill("websockets")`** - JaypieWebSocket and JaypieWebSocketTable constructs

package/skills/skills.md

@@ -17,7 +17,7 @@ Look up skills by alias: `mcp__jaypie__skill(alias)`
 |----------|--------|
 | contents | index, releasenotes |
 | development | apikey, documentation, errors, llm, logs, mocks, monorepo, repokit, style, subpackages, tests, tools |
-| infrastructure | apigateway, aws, cdk, cicd, datadog, dns, dynamodb, express, lambda, migrations, secrets, sqs, streaming, variables, web, websockets |
+| infrastructure | apigateway, aws, cdk, cicd, datadog, dns, dynamodb, express, lambda, migrations, secrets, sqs, streaming, variables, waf, web, websockets |
 | patterns | api, fabric, handlers, models, services, vocabulary |
 | recipes | recipe-api-server |
 | meta | issues, jaypie, mcp, skills |

package/skills/waf.md

@@ -0,0 +1,154 @@
+---
+description: WAF (Web Application Firewall) configuration for JaypieDistribution
+related: aws, cdk, web
+---
+
+# WAF (Web Application Firewall)
+
+`JaypieDistribution` (and `JaypieWebDeploymentBucket`) attach a WAFv2 WebACL by
+default with:
+
+- **AWSManagedRulesCommonRuleSet** — OWASP top 10 (SQLi, XSS, etc.)
+- **AWSManagedRulesKnownBadInputsRuleSet** — known bad patterns (Log4j, etc.)
+- **Rate limiting** — 2000 requests per 5 minutes per IP
+- **WAF logging** — S3 bucket with Datadog forwarder notifications
+
+```typescript
+// Default: WAF enabled with logging
+new JaypieDistribution(this, "Dist", { handler });
+
+// Disable WAF entirely
+new JaypieDistribution(this, "Dist", { handler, waf: false });
+
+// Customize rate limit (name required on any waf config object)
+new JaypieDistribution(this, "Dist", {
+  handler,
+  waf: { name: "api", rateLimitPerIp: 500 },
+});
+
+// Multiple distributions in one env — set a unique waf.name on each to
+// avoid WebACL/S3 bucket name collisions between stacks.
+new JaypieDistribution(this, "Api", { handler: api, waf: { name: "api" } });
+new JaypieDistribution(this, "Mcp", { handler: mcp, waf: { name: "mcp" } });
+
+// Use existing WebACL
+new JaypieDistribution(this, "Dist", {
+  handler,
+  waf: { name: "api", webAclArn: "arn:aws:wafv2:..." },
+});
+
+// Disable WAF logging only
+new JaypieDistribution(this, "Dist", {
+  handler,
+  waf: { name: "api", logBucket: false },
+});
+
+// Bring your own WAF logging bucket
+new JaypieDistribution(this, "Dist", {
+  handler,
+  waf: { name: "api", logBucket: myWafBucket },
+});
+```
+
+Cost: $5/month per WebACL + $1/month per rule + $0.60 per million requests. Use
+`waf: false` to opt out.
+
+## Override specific managed rule actions
+
+Flip a named sub-rule from `block` to `count` everywhere (e.g. allow large
+request bodies):
+
+```typescript
+new JaypieDistribution(this, "Dist", {
+  handler,
+  waf: {
+    name: "api",
+    managedRuleOverrides: {
+      AWSManagedRulesCommonRuleSet: [
+        { name: "SizeRestrictions_BODY", actionToUse: { count: {} } },
+      ],
+    },
+  },
+});
+```
+
+## Scope a managed rule group to specific URL patterns
+
+```typescript
+new JaypieDistribution(this, "Dist", {
+  handler,
+  waf: {
+    name: "api",
+    managedRuleScopeDowns: {
+      // Only run the CommonRuleSet for paths OTHER than /chat — lets /chat
+      // handle large AI-generated request bodies without weakening protection
+      // elsewhere.
+      AWSManagedRulesCommonRuleSet: {
+        notStatement: {
+          statement: {
+            byteMatchStatement: {
+              fieldToMatch: { uriPath: {} },
+              positionalConstraint: "STARTS_WITH",
+              searchString: "/chat",
+              textTransformations: [{ priority: 0, type: "NONE" }],
+            },
+          },
+        },
+      },
+    },
+  },
+});
+```
+
+## Relaxing a managed rule for specific paths — `waf.allow`
+
+`allow` relaxes named rules to **count** mode for matching paths, leaving full
+blocking everywhere else. Each entry names one or more paths and, per managed
+rule group key, the sub-rule names to flip:
+
+```typescript
+new JaypieDistribution(this, "Dist", {
+  handler,
+  waf: {
+    name: "api",
+    allow: [
+      {
+        path: "/hooks/*", // trailing * → STARTS_WITH; otherwise EXACTLY
+        AWSManagedRulesCommonRuleSet: ["NoUserAgent_HEADER"],
+        AWSManagedRulesKnownBadInputsRuleSet: ["ExploitablePaths_URIPATH"],
+      },
+    ],
+  },
+});
+```
+
+- A `path` ending in `*` compiles to a `STARTS_WITH` byte-match; otherwise
+  `EXACTLY`. `/hooks/*` matches `/hooks/ping` but **not** bare `/hooks`.
+- The key (e.g. `AWSManagedRulesCommonRuleSet`) must be one of the active
+  `managedRules`.
+- `allow` composes with `managedRuleOverrides`: the baseline overrides apply to
+  both the relaxed and strict emissions of a group; entries in `allow` further
+  relax specific (path × sub-rule) intersections. Groups not named in `allow`
+  keep their single-rule emission.
+
+## ⚠️ Rule name ≠ label (casing trap)
+
+AWS uses different casing for a rule's **label** (seen in WAF logs) and its
+**name**. `managedRuleOverrides` / `allow` match on the **rule name**:
+
+| Label (seen in WAF logs)                              | Rule name (use this) |
+| ----------------------------------------------------- | -------------------- |
+| `awswaf:managed:aws:core-rule-set:NoUserAgent_Header` | `NoUserAgent_HEADER` |
+
+Jaypie now validates rule names against each AWS managed rule group at synth and
+throws a `ConfigurationError` listing the valid names on a mismatch (custom rule
+groups are not validated). Historically a name that matched no rule was
+**silently ignored** — the rule kept blocking. If a relaxation "isn't working,"
+read the WAF log `terminatingRule.<NAME>` and copy that exact name (e.g.
+`NoUserAgent_HEADER`, `SizeRestrictions_BODY`, `UserAgent_BadBots_HEADER`).
+
+## See Also
+
+- **`skill("cdk")`** - CDK constructs and deployment patterns
+- **`skill("aws")`** - AWS SDK utilities
+- **`skill("web")`** - JaypieWebDeploymentBucket and JaypieStaticWebBucket