@jaypie/mcp 0.8.63 → 0.8.65

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.63#4149aed3"
+const BUILD_VERSION_STRING = "@jaypie/mcp@0.8.65#58028ec6"
     ;
 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.63",
+  "version": "0.8.65",
   "description": "Jaypie MCP",
   "repository": {
     "type": "git",

package/release-notes/constructs/1.2.59.md

@@ -0,0 +1,14 @@
+---
+version: 1.2.59
+date: 2026-06-03
+summary: Add JaypieSecret base construct and serviceTag on lambda constructs
+---
+
+## @jaypie/constructs 1.2.59
+
+### Features
+
+- **JaypieSecret**: New base construct — a plain AWS Secrets Manager secret without the environment-driven provider/consumer cross-stack pattern. Reads its value from `process.env[envKey]`, an explicit `value`, or `generateSecretString`, and throws `ConfigurationError` when an `envKey` resolves to nothing. Supports the same SCREAMING_SNAKE_CASE shorthand as `JaypieEnvSecret` (construct id `Secret_${envKey}`).
+- **JaypieEnvSecret** now extends `JaypieSecret`, layering the env-aware provider/consumer behavior on top via a `buildSecret` override. Existing behavior — including issue #347 cross-stack export names — is preserved. `JaypieEnvSecret` is deprecated and will be removed in 2.0.
+- **resolveSecrets / lambda `secrets`**: `SecretsArrayItem` widened to `JaypieSecret | string`, so any `JaypieSecret` (including `JaypieEnvSecret`) is accepted wherever secrets are passed. Strings still create env-aware `JaypieEnvSecret` instances.
+- **serviceTag**: `JaypieLambda` (and `JaypieExpressLambda`, `JaypieWebSocketLambda` by inheritance) accepts a `serviceTag` prop that applies `CDK.TAG.SERVICE` alongside `roleTag` and `vendorTag`. `JaypieQueuedLambda` propagates it to the SQS queue and `JaypieBucketQueuedLambda` to the S3 bucket.

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/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/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/secrets.md

@@ -5,7 +5,30 @@ related: apikey, aws, cdk, variables
 
 # Secret Management
 
-Jaypie uses AWS Secrets Manager for secure credential storage. The `JaypieEnvSecret` construct creates secrets at deploy time from environment variables, and `getEnvSecret` retrieves them at runtime.
+Jaypie uses AWS Secrets Manager for secure credential storage. The `JaypieSecret` and `JaypieEnvSecret` constructs create secrets at deploy time from environment variables, and `getEnvSecret` retrieves them at runtime.
+
+## JaypieSecret vs JaypieEnvSecret
+
+- **`JaypieSecret`** — a plain secret. Always creates a secret in the current stack from `process.env[envKey]`, an explicit `value`, or `generateSecretString`. No cross-stack imports or exports. This is the construct to reach for.
+- **`JaypieEnvSecret`** — extends `JaypieSecret` and adds the environment-driven provider/consumer cross-stack pattern (see [Provider/Consumer Pattern](#providerconsumer-pattern) below). **Deprecated; will be removed in 2.0.**
+
+`JaypieEnvSecret` is a `JaypieSecret`, so it is accepted anywhere a `JaypieSecret` is — including the `secrets` array on `JaypieLambda`. Strings in that array still create env-aware `JaypieEnvSecret` instances.
+
+```typescript
+import { JaypieSecret } from "@jaypie/constructs";
+
+// Reads process.env.MY_API_KEY at deploy time
+// Throws ConfigurationError if unset and no value/generateSecretString given
+new JaypieSecret(this, "MY_API_KEY");
+
+// Generated secret, no env var needed
+new JaypieSecret(this, "DbPassword", {
+  envKey: "DB_PASSWORD",
+  generateSecretString: { excludePunctuation: true, passwordLength: 32 },
+});
+```
+
+Everything below that uses `JaypieEnvSecret` works the same on `JaypieSecret`, except the provider/consumer cross-stack behavior, which is `JaypieEnvSecret`-only.
 
 ## The Pattern
 

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