@everystack/mcp 0.4.1 → 0.4.2

package/dist/caching.md

@@ -0,0 +1,78 @@
+# Caching & WAF (CloudFront Edge)
+
+> The edge pipeline: WAF filters malicious traffic, edge auth verifies JWTs, CloudFront caches public GETs and SSR HTML, the handler sets `Cache-Control` by auth state, and mutations bump epoch keys that invalidate stale entries. Read the WAF section BEFORE enabling managed rules — the default managed rules 403 every PostgREST/JSON API request without the shipped exclusions.
+
+## THE TRAP — AWS managed rules 403 your JSON API
+
+AWS WAF managed rules inspect the **request body and headers**, not just the URL. The moment you enable them on a PostgREST/JSON API, several rules fire on legitimate traffic and return **403 before the request ever reaches Lambda**:
+
+- `AWSManagedRulesSQLiRuleSet` → **`SQLi_BODY`**: PostgREST JSON keys (`limit`, `select`, `order`, `sort`) read as SQL keywords. Every `POST`/RPC and every `select()` with those keys 403s.
+- `AWSManagedRulesCommonRuleSet` → **`SizeRestrictions_BODY`** (large JSON payloads) and **`GenericRFI_BODY`** (URLs inside JSON values look like remote-file-inclusion).
+- `AWSManagedRulesKnownBadInputsRuleSet` → **`Log4JRCE_HEADER`**: the JWT in the `Authorization` header trips the Log4Shell signature.
+
+These are false positives — Drizzle parameterizes every query server-side, so none of it is real injection. But WAF has no application context and blocks anyway.
+
+> Do NOT "exclude `SQLi_QUERYARGUMENTS`." That rule lives in `AWSManagedRulesSQLiRuleSet`, and a `ruleActionOverride` naming a rule that isn't in the group you attach it to **silently no-ops** — the exclusion looks configured while the BODY rules keep 403-ing. Exclude the BODY/HEADER rules named above.
+
+### The fix — two composed transforms
+
+everystack ships the exclusion set and a rate-limit-429 transform in `@everystack/server/cdn`. Set the false-positive rules to **COUNT** mode (they still log to CloudWatch `AWS/WAFV2`, they just stop blocking) and answer rate limits with **429** instead of 403:
+
+```ts
+import { applyWafExclusions, applyWafRateLimit429 } from '@everystack/server/cdn';
+
+// MUST be registered BEFORE `new sst.aws.Router(...)`. A $transform only applies to
+// resources created AFTER it, and the Router is what creates the WebAcl — register it
+// after the Router and it silently no-ops.
+$transform(aws.wafv2.WebAcl, (args: any) => {
+  if (!args.rules) return;
+  args.rules = $resolve(args.rules).apply(
+    (rules: any[]) => applyWafRateLimit429(applyWafExclusions(rules)),
+  );
+});
+
+const router = new sst.aws.Router('Router', {
+  // ...
+  waf: {
+    rateLimitPerIp: 2000,
+    managedRules: { common: true, sqli: true, knownBadInputs: true },
+  },
+});
+```
+
+- **COUNT ≠ disabled.** The rule still evaluates and records to CloudWatch — you keep visibility, you just stop the false-positive block. Nothing is turned off.
+- **`applyWafExclusions(rules, overrides?)`** defaults to the shipped `WAF_JSON_API_OVERRIDES` map. Pass a second argument (rule group → rule names) to extend it if you hit a new false positive.
+- **`applyWafRateLimit429`** rewrites rate-based block actions to `429 + Retry-After`. This is SEO-load-bearing, not cosmetic: Google reads any 4xx except 429 as "gone" and deindexes the URL over days; 429 means "back off and retry." A rate-limited public SSR site returning 403 becomes a deindexing engine.
+
+### GET-filter false positives (diagnosing new ones)
+
+PostgREST GET syntax (`?title=eq.hello`, `?or=(status.eq.draft,status.eq.review)`) can trip query-argument SQLi signatures that are NOT in the default map. Don't guess — turn on `waf.logging`, read the WAF **sampled requests** in the console to find the exact rule that matched, then add it via the second argument to `applyWafExclusions`. Set the offending rule to COUNT, confirm the request passes, and keep watching the count metric.
+
+## WAF configuration
+
+`sst.aws.Router`'s `waf` block configures rate limiting and managed rule sets:
+
+| Field | Purpose |
+| --- | --- |
+| `rateLimitPerIp` | Per-IP request cap over a 5-minute sliding window. On exceed, WAF 403s (429 with the transform above) until the window resets. `2000` (~6.7 req/s sustained) suits most APIs. |
+| `managedRules.common` | `AWSManagedRulesCommonRuleSet` — broad OWASP-style protections. |
+| `managedRules.sqli` | `AWSManagedRulesSQLiRuleSet` — SQL-injection signatures. |
+| `managedRules.knownBadInputs` | `AWSManagedRulesKnownBadInputsRuleSet` — known exploit payloads (Log4Shell, etc.). |
+
+All three managed sets are AWS Free-Tier rules (~$1/rule-group/month + per-request); no per-request cost beyond base WAF pricing.
+
+**What WAF does NOT cover** (it sees IPs and HTTP, not application state):
+- Per-account auth brute force — that belongs in `@everystack/auth` (account lockout, progressive delays). WAF rate limiting is per-IP.
+- Bot quality — AWS Bot Control (Targeted) can fingerprint sophisticated bots but costs $10/M requests; managed rules + rate limiting suffice for most apps.
+
+## The rest of the edge pipeline
+
+**Edge auth.** For latency-sensitive authenticated paths, a CloudFront function verifies the JWT signature at the edge before the request reaches Lambda. See `everystack://auth` for `authFeature` / `composeViewerRequest` and edge token lifetimes (keep edge access tokens short, ~15 min).
+
+**Response caching (Cache-Control by auth state).** The handler sets headers based on authentication:
+- Public GETs and SSR HTML → cacheable at the edge (`public, max-age=...`). SSR HTML is the same for every visitor (good for SEO); user-specific content loads on the client during rehydration.
+- Authenticated API responses → `private, no-store`, bypassing the CDN cache entirely.
+
+**Epoch invalidation.** Mutations bump an epoch-based version key (in the CloudFront KVS), which naturally invalidates stale public cache entries — no manual purging. Reads carry the current epoch; a write advances it so subsequent reads miss the old cached copy.
+
+**Debugging an edge 403.** A 403 with **no corresponding Lambda log entry** was blocked at the edge (WAF or edge auth), not by your handler. Check the WAF sampled requests for the matched rule, confirm with `curl -sI` against the API path, and reach for the exclusions transform above. A 403 that DOES reach Lambda is an application authz decision, not WAF.

package/dist/deployment.md

@@ -59,6 +59,9 @@ export default $config({
     const router = new sst.aws.Router('Router', {
       routes: { '/*': api.url },
     });
+    // Adding WAF (`waf: { managedRules, rateLimitPerIp }`)? Read everystack://caching
+    // FIRST — AWS managed rules 403 every PostgREST request without the shipped
+    // exclusions transform, which must register BEFORE this Router.
 
     // CLI needs these outputs
     return {

package/dist/expo-server-deploy.md

@@ -92,6 +92,7 @@ Your OTHER `+api.ts` routes (`app/mcp+api.ts`, `app/games/[id]+api.ts`, ...) nee
 
 ```typescript
 // server/ops.ts
+import { Resource } from 'sst';
 import { createPluginLambdaHandler, dbPlugin } from '@everystack/server/plugin';
 import { createAppContext, appPlugins } from './context';
 
@@ -104,6 +105,10 @@ export const handler = createPluginLambdaHandler({
       migrationsFolder: 'drizzle',
       seed: async (db, schema) => (await import('../db/seed.js')).runSeed(db, schema),
       //    ^ lazy import — a top-level import would run at Lambda INIT and crash the boot
+      backupBucket: Resource.Backups?.name,
+      //    ^ registers db:backup / db:backups / db:restore. Omit it and those actions
+      //      return "backup storage not configured"; omit the whole ops Lambda and the
+      //      CLI can't reach them at all — it reports "Unknown action" (see Gotchas).
     }),
   ],
 });
@@ -133,6 +138,7 @@ export default $config({
 
     const updates = new sst.aws.Bucket('Updates');            // published Expo exports (server bundles)
     const clientBundles = new sst.aws.Bucket('ClientBundles', { access: 'cloudfront' });
+    const backups = new sst.aws.Bucket('Backups');            // private — logical pg_dump backups (db:backup)
 
     const jwtSecret = new sst.Secret('JwtSecret');
     // Least-privilege API credential — written by `everystack db:provision`.
@@ -162,17 +168,19 @@ export default $config({
       runtime: 'nodejs20.x',
       timeout: '120 seconds',
       vpc,
-      link: [database, databaseUrl, updates, clientBundles, jwtSecret],
+      link: [database, databaseUrl, updates, clientBundles, jwtSecret, backups],
       copyFiles: [{ from: 'drizzle', to: 'drizzle' }],   // migrations must ship with the ops bundle
     });
 
-    // The CLI discovers resources through these outputs — all five are required.
+    // The CLI discovers resources through these outputs. The first five are required;
+    // backupsBucket unlocks db:backup / db:swap / db:fork (also auto-discovered by bucket name).
     return {
       routerUrl: router.url,
       apiFunctionName: api.name,
       opsFunctionName: ops.name,
       updatesBucket: updates.name,
       clientBundlesBucket: clientBundles.name,
+      backupsBucket: backups.name,
     };
   },
 });
@@ -205,4 +213,5 @@ Subsequent app-code ships are `everystack update` alone — no `sst deploy`, no
 - **A path claimed by a plugin never reaches your bundle's route.** If you mount the everystack handler at `/api`, a bundle route at `app/api/foo+api.ts` is shadowed in production (it still serves in local dev unless the catch-all shadows it there too — keep the surfaces aligned).
 - **Lazy-load your seed** (shown above). A top-level `import { runSeed }` in an entrypoint runs at Lambda INIT, tries to reach the database before configuration, and kills the boot.
 - **`copyFiles` the migrations folder** into the ops function, or `db:migrate` fails with ENOENT.
+- **`db:backup`/`db:export`/`db:restore` run in the ephemeral Fargate Task lane — wire `dbTaskPlugin({ backupBucket })` on the ops function.** They are pg_dump/pg_restore work; the ops Lambda holds no pg binaries. `everystack db:backup` reporting `Unknown action: db:backup` means the CLI reached a function with no `dbTaskPlugin` mounted (usually: no ops function at all, so `opsFunctionName` fell back to the Api Lambda). Deploy the `Ops` function above with `dbTaskPlugin`. If instead it reports `backup storage not configured`, `dbTaskPlugin` is mounted but `backupBucket` is unset — pass `() => Resource.Backups.name`. The Task image's `pg_dump`-vs-server compatibility is verified on demand by `everystack task:probe` (there is no Lambda pg_dump layer).
 - **`+api.ts` routes run with the bundle's environment**, not per-route SST links. Resource-linked work (secrets, buckets) belongs in plugins on the Lambda side; keep bundle routes to app logic over the request.

package/dist/index.cjs

@@ -21652,6 +21652,12 @@ var RESOURCES = [
     description: "SST deployment: sst.config.ts setup, secrets, stages (dev/production), CloudFront, Lambda configuration, VPC, RDS Aurora Serverless, resource linking.",
     filename: "deployment.md"
   },
+  {
+    uri: "everystack://caching",
+    name: "Caching & WAF (CloudFront Edge)",
+    description: "READ BEFORE enabling WAF on the Router. AWS managed rules 403 every PostgREST/JSON API request without the shipped exclusions transform (applyWafExclusions/applyWafRateLimit429 from @everystack/server/cdn). Also: edge auth, response caching by auth state, epoch invalidation, and debugging edge 403s.",
+    filename: "caching.md"
+  },
   {
     uri: "everystack://expo-server-deploy",
     name: "Deploying an Expo Router Server App",
@@ -22478,6 +22484,7 @@ function registerDeployPrompt(server) {
                 "1. Read everystack://deployment for infrastructure setup.",
                 "2. Read everystack://security for AWS credential setup and deployment checklist.",
                 "3. Read everystack://database-operations for the SAFE schema-migration flow (db:plan \u2192 db:apply, snapshot-first) \u2014 a protected stage is NOT migrated with db:migrate.",
+                "   If the deploy enables WAF (`waf` on the Router), read everystack://caching first \u2014 the managed rules 403 every PostgREST request without the shipped exclusions transform, which must register BEFORE the Router.",
                 projectPath ? `4. Run check_environment with projectPath="${projectPath}" to confirm prerequisites (Node, SST, AWS credentials) before deploying.` : "",
                 "",
                 "## Pre-Deploy Checklist",
@@ -22619,6 +22626,8 @@ function registerDebugPrompt(server) {
                 "",
                 "If the symptom involves authentication or authorization:",
                 "",
+                "- **First, edge vs handler:** a 403 with NO matching Lambda log entry was blocked at the edge (WAF or edge auth), not by your handler. This is common right after enabling `waf` managed rules \u2014 the AWS SQLi/body rules 403 every PostgREST request. Check the WAF sampled requests and read everystack://caching for the exclusions transform. A 403 that DOES reach Lambda is an application authz decision \u2014 continue below.",
+                "",
                 "- **Check token flow:**",
                 "  - Is the JWT being sent in the Authorization header?",
                 "  - Is the token expired? Decode at jwt.io and check `exp`",
@@ -22922,6 +22931,7 @@ function registerSecurePrompt(server) {
                   "- Rejects expired or malformed tokens at the edge",
                   "- Reduces Lambda invocations for unauthorized requests",
                   "- See everystack://deployment for CloudFront function setup",
+                  "- WAF at the edge: everystack://caching \u2014 enabling AWS managed rules without the shipped exclusions 403s every PostgREST request",
                   ""
                 ].join("\n") : "",
                 "## Verification",
@@ -23723,7 +23733,7 @@ async function runGovernanceCli(argv) {
 }
 
 // src/index.ts
-var version2 = (true ? "0.4.1" : null) ?? "0.3.0-dev";
+var version2 = (true ? "0.4.2" : null) ?? "0.3.0-dev";
 var INSTRUCTIONS = [
   "You govern how any agent builds everystack \u2014 a self-hosted application stack for Expo apps on AWS.",
   "Your job is not only to advise but to keep the build on-script: the architecture the maintainer",

package/dist/security.md

@@ -263,8 +263,8 @@ RESET ROLE;
 - [ ] Bcrypt cost >= 10
 
 ### Infrastructure
-- [ ] WAF managed rules (exclude SQLi_QUERYARGUMENTS on API paths for PostgREST syntax)
-- [ ] Rate limiting (1000 req/5 min per IP)
+- [ ] WAF managed rules — set the JSON-API false-positive BODY/HEADER rules (SQLi_BODY, SizeRestrictions_BODY, GenericRFI_BODY, Log4JRCE_HEADER) to COUNT via `applyWafExclusions`, or they 403 every PostgREST request. See everystack://caching (read BEFORE enabling `waf` on the Router).
+- [ ] Rate limiting — 429 not 403 (applyWafRateLimit429); ~2000 req/5 min per IP. See everystack://caching.
 - [ ] CloudFront edge JWT verification for latency-sensitive paths
 - [ ] Database credentials via SST Resource linking
 - [ ] No debug endpoints or env dumps in production

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/mcp",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "Governance layer that governs how any agent builds everystack — grounding, cheat gates, and Model-aware tooling over MCP",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",
@@ -40,8 +40,9 @@
     "tsx": "4.21.0",
     "typescript": "5.9.3",
     "zod": "3.25.67",
-    "@everystack/cli": "0.4.19",
-    "@everystack/model": "0.4.4"
+    "@everystack/cli": "0.4.32",
+    "@everystack/model": "0.4.5",
+    "@everystack/server": "0.4.14"
   },
   "scripts": {
     "test": "jest",

package/src/prompts/debug.ts

@@ -33,6 +33,8 @@ export function registerDebugPrompt(server: McpServer): void {
                 '',
                 'If the symptom involves authentication or authorization:',
                 '',
+                '- **First, edge vs handler:** a 403 with NO matching Lambda log entry was blocked at the edge (WAF or edge auth), not by your handler. This is common right after enabling `waf` managed rules — the AWS SQLi/body rules 403 every PostgREST request. Check the WAF sampled requests and read everystack://caching for the exclusions transform. A 403 that DOES reach Lambda is an application authz decision — continue below.',
+                '',
                 '- **Check token flow:**',
                 '  - Is the JWT being sent in the Authorization header?',
                 '  - Is the token expired? Decode at jwt.io and check `exp`',

package/src/prompts/deploy.ts

@@ -26,6 +26,7 @@ export function registerDeployPrompt(server: McpServer): void {
                 '1. Read everystack://deployment for infrastructure setup.',
                 '2. Read everystack://security for AWS credential setup and deployment checklist.',
                 '3. Read everystack://database-operations for the SAFE schema-migration flow (db:plan → db:apply, snapshot-first) — a protected stage is NOT migrated with db:migrate.',
+                '   If the deploy enables WAF (`waf` on the Router), read everystack://caching first — the managed rules 403 every PostgREST request without the shipped exclusions transform, which must register BEFORE the Router.',
                 projectPath ? `4. Run check_environment with projectPath="${projectPath}" to confirm prerequisites (Node, SST, AWS credentials) before deploying.` : '',
                 '',
                 '## Pre-Deploy Checklist',

package/src/prompts/secure.ts

@@ -208,6 +208,7 @@ export function registerSecurePrompt(server: McpServer): void {
                   '- Rejects expired or malformed tokens at the edge',
                   '- Reduces Lambda invocations for unauthorized requests',
                   '- See everystack://deployment for CloudFront function setup',
+                  '- WAF at the edge: everystack://caching — enabling AWS managed rules without the shipped exclusions 403s every PostgREST request',
                   '',
                 ].join('\n') : '',
 

package/src/resources/caching.md

@@ -0,0 +1,78 @@
+# Caching & WAF (CloudFront Edge)
+
+> The edge pipeline: WAF filters malicious traffic, edge auth verifies JWTs, CloudFront caches public GETs and SSR HTML, the handler sets `Cache-Control` by auth state, and mutations bump epoch keys that invalidate stale entries. Read the WAF section BEFORE enabling managed rules — the default managed rules 403 every PostgREST/JSON API request without the shipped exclusions.
+
+## THE TRAP — AWS managed rules 403 your JSON API
+
+AWS WAF managed rules inspect the **request body and headers**, not just the URL. The moment you enable them on a PostgREST/JSON API, several rules fire on legitimate traffic and return **403 before the request ever reaches Lambda**:
+
+- `AWSManagedRulesSQLiRuleSet` → **`SQLi_BODY`**: PostgREST JSON keys (`limit`, `select`, `order`, `sort`) read as SQL keywords. Every `POST`/RPC and every `select()` with those keys 403s.
+- `AWSManagedRulesCommonRuleSet` → **`SizeRestrictions_BODY`** (large JSON payloads) and **`GenericRFI_BODY`** (URLs inside JSON values look like remote-file-inclusion).
+- `AWSManagedRulesKnownBadInputsRuleSet` → **`Log4JRCE_HEADER`**: the JWT in the `Authorization` header trips the Log4Shell signature.
+
+These are false positives — Drizzle parameterizes every query server-side, so none of it is real injection. But WAF has no application context and blocks anyway.
+
+> Do NOT "exclude `SQLi_QUERYARGUMENTS`." That rule lives in `AWSManagedRulesSQLiRuleSet`, and a `ruleActionOverride` naming a rule that isn't in the group you attach it to **silently no-ops** — the exclusion looks configured while the BODY rules keep 403-ing. Exclude the BODY/HEADER rules named above.
+
+### The fix — two composed transforms
+
+everystack ships the exclusion set and a rate-limit-429 transform in `@everystack/server/cdn`. Set the false-positive rules to **COUNT** mode (they still log to CloudWatch `AWS/WAFV2`, they just stop blocking) and answer rate limits with **429** instead of 403:
+
+```ts
+import { applyWafExclusions, applyWafRateLimit429 } from '@everystack/server/cdn';
+
+// MUST be registered BEFORE `new sst.aws.Router(...)`. A $transform only applies to
+// resources created AFTER it, and the Router is what creates the WebAcl — register it
+// after the Router and it silently no-ops.
+$transform(aws.wafv2.WebAcl, (args: any) => {
+  if (!args.rules) return;
+  args.rules = $resolve(args.rules).apply(
+    (rules: any[]) => applyWafRateLimit429(applyWafExclusions(rules)),
+  );
+});
+
+const router = new sst.aws.Router('Router', {
+  // ...
+  waf: {
+    rateLimitPerIp: 2000,
+    managedRules: { common: true, sqli: true, knownBadInputs: true },
+  },
+});
+```
+
+- **COUNT ≠ disabled.** The rule still evaluates and records to CloudWatch — you keep visibility, you just stop the false-positive block. Nothing is turned off.
+- **`applyWafExclusions(rules, overrides?)`** defaults to the shipped `WAF_JSON_API_OVERRIDES` map. Pass a second argument (rule group → rule names) to extend it if you hit a new false positive.
+- **`applyWafRateLimit429`** rewrites rate-based block actions to `429 + Retry-After`. This is SEO-load-bearing, not cosmetic: Google reads any 4xx except 429 as "gone" and deindexes the URL over days; 429 means "back off and retry." A rate-limited public SSR site returning 403 becomes a deindexing engine.
+
+### GET-filter false positives (diagnosing new ones)
+
+PostgREST GET syntax (`?title=eq.hello`, `?or=(status.eq.draft,status.eq.review)`) can trip query-argument SQLi signatures that are NOT in the default map. Don't guess — turn on `waf.logging`, read the WAF **sampled requests** in the console to find the exact rule that matched, then add it via the second argument to `applyWafExclusions`. Set the offending rule to COUNT, confirm the request passes, and keep watching the count metric.
+
+## WAF configuration
+
+`sst.aws.Router`'s `waf` block configures rate limiting and managed rule sets:
+
+| Field | Purpose |
+| --- | --- |
+| `rateLimitPerIp` | Per-IP request cap over a 5-minute sliding window. On exceed, WAF 403s (429 with the transform above) until the window resets. `2000` (~6.7 req/s sustained) suits most APIs. |
+| `managedRules.common` | `AWSManagedRulesCommonRuleSet` — broad OWASP-style protections. |
+| `managedRules.sqli` | `AWSManagedRulesSQLiRuleSet` — SQL-injection signatures. |
+| `managedRules.knownBadInputs` | `AWSManagedRulesKnownBadInputsRuleSet` — known exploit payloads (Log4Shell, etc.). |
+
+All three managed sets are AWS Free-Tier rules (~$1/rule-group/month + per-request); no per-request cost beyond base WAF pricing.
+
+**What WAF does NOT cover** (it sees IPs and HTTP, not application state):
+- Per-account auth brute force — that belongs in `@everystack/auth` (account lockout, progressive delays). WAF rate limiting is per-IP.
+- Bot quality — AWS Bot Control (Targeted) can fingerprint sophisticated bots but costs $10/M requests; managed rules + rate limiting suffice for most apps.
+
+## The rest of the edge pipeline
+
+**Edge auth.** For latency-sensitive authenticated paths, a CloudFront function verifies the JWT signature at the edge before the request reaches Lambda. See `everystack://auth` for `authFeature` / `composeViewerRequest` and edge token lifetimes (keep edge access tokens short, ~15 min).
+
+**Response caching (Cache-Control by auth state).** The handler sets headers based on authentication:
+- Public GETs and SSR HTML → cacheable at the edge (`public, max-age=...`). SSR HTML is the same for every visitor (good for SEO); user-specific content loads on the client during rehydration.
+- Authenticated API responses → `private, no-store`, bypassing the CDN cache entirely.
+
+**Epoch invalidation.** Mutations bump an epoch-based version key (in the CloudFront KVS), which naturally invalidates stale public cache entries — no manual purging. Reads carry the current epoch; a write advances it so subsequent reads miss the old cached copy.
+
+**Debugging an edge 403.** A 403 with **no corresponding Lambda log entry** was blocked at the edge (WAF or edge auth), not by your handler. Check the WAF sampled requests for the matched rule, confirm with `curl -sI` against the API path, and reach for the exclusions transform above. A 403 that DOES reach Lambda is an application authz decision, not WAF.

package/src/resources/deployment.md

@@ -59,6 +59,9 @@ export default $config({
     const router = new sst.aws.Router('Router', {
       routes: { '/*': api.url },
     });
+    // Adding WAF (`waf: { managedRules, rateLimitPerIp }`)? Read everystack://caching
+    // FIRST — AWS managed rules 403 every PostgREST request without the shipped
+    // exclusions transform, which must register BEFORE this Router.
 
     // CLI needs these outputs
     return {

package/src/resources/expo-server-deploy.md

@@ -92,6 +92,7 @@ Your OTHER `+api.ts` routes (`app/mcp+api.ts`, `app/games/[id]+api.ts`, ...) nee
 
 ```typescript
 // server/ops.ts
+import { Resource } from 'sst';
 import { createPluginLambdaHandler, dbPlugin } from '@everystack/server/plugin';
 import { createAppContext, appPlugins } from './context';
 
@@ -104,6 +105,10 @@ export const handler = createPluginLambdaHandler({
       migrationsFolder: 'drizzle',
       seed: async (db, schema) => (await import('../db/seed.js')).runSeed(db, schema),
       //    ^ lazy import — a top-level import would run at Lambda INIT and crash the boot
+      backupBucket: Resource.Backups?.name,
+      //    ^ registers db:backup / db:backups / db:restore. Omit it and those actions
+      //      return "backup storage not configured"; omit the whole ops Lambda and the
+      //      CLI can't reach them at all — it reports "Unknown action" (see Gotchas).
     }),
   ],
 });
@@ -133,6 +138,7 @@ export default $config({
 
     const updates = new sst.aws.Bucket('Updates');            // published Expo exports (server bundles)
     const clientBundles = new sst.aws.Bucket('ClientBundles', { access: 'cloudfront' });
+    const backups = new sst.aws.Bucket('Backups');            // private — logical pg_dump backups (db:backup)
 
     const jwtSecret = new sst.Secret('JwtSecret');
     // Least-privilege API credential — written by `everystack db:provision`.
@@ -162,17 +168,19 @@ export default $config({
       runtime: 'nodejs20.x',
       timeout: '120 seconds',
       vpc,
-      link: [database, databaseUrl, updates, clientBundles, jwtSecret],
+      link: [database, databaseUrl, updates, clientBundles, jwtSecret, backups],
       copyFiles: [{ from: 'drizzle', to: 'drizzle' }],   // migrations must ship with the ops bundle
     });
 
-    // The CLI discovers resources through these outputs — all five are required.
+    // The CLI discovers resources through these outputs. The first five are required;
+    // backupsBucket unlocks db:backup / db:swap / db:fork (also auto-discovered by bucket name).
     return {
       routerUrl: router.url,
       apiFunctionName: api.name,
       opsFunctionName: ops.name,
       updatesBucket: updates.name,
       clientBundlesBucket: clientBundles.name,
+      backupsBucket: backups.name,
     };
   },
 });
@@ -205,4 +213,5 @@ Subsequent app-code ships are `everystack update` alone — no `sst deploy`, no
 - **A path claimed by a plugin never reaches your bundle's route.** If you mount the everystack handler at `/api`, a bundle route at `app/api/foo+api.ts` is shadowed in production (it still serves in local dev unless the catch-all shadows it there too — keep the surfaces aligned).
 - **Lazy-load your seed** (shown above). A top-level `import { runSeed }` in an entrypoint runs at Lambda INIT, tries to reach the database before configuration, and kills the boot.
 - **`copyFiles` the migrations folder** into the ops function, or `db:migrate` fails with ENOENT.
+- **`db:backup`/`db:export`/`db:restore` run in the ephemeral Fargate Task lane — wire `dbTaskPlugin({ backupBucket })` on the ops function.** They are pg_dump/pg_restore work; the ops Lambda holds no pg binaries. `everystack db:backup` reporting `Unknown action: db:backup` means the CLI reached a function with no `dbTaskPlugin` mounted (usually: no ops function at all, so `opsFunctionName` fell back to the Api Lambda). Deploy the `Ops` function above with `dbTaskPlugin`. If instead it reports `backup storage not configured`, `dbTaskPlugin` is mounted but `backupBucket` is unset — pass `() => Resource.Backups.name`. The Task image's `pg_dump`-vs-server compatibility is verified on demand by `everystack task:probe` (there is no Lambda pg_dump layer).
 - **`+api.ts` routes run with the bundle's environment**, not per-route SST links. Resource-linked work (secrets, buckets) belongs in plugins on the Lambda side; keep bundle routes to app logic over the request.

package/src/resources/index.ts

@@ -140,6 +140,13 @@ const RESOURCES: ResourceDef[] = [
       'SST deployment: sst.config.ts setup, secrets, stages (dev/production), CloudFront, Lambda configuration, VPC, RDS Aurora Serverless, resource linking.',
     filename: 'deployment.md',
   },
+  {
+    uri: 'everystack://caching',
+    name: 'Caching & WAF (CloudFront Edge)',
+    description:
+      'READ BEFORE enabling WAF on the Router. AWS managed rules 403 every PostgREST/JSON API request without the shipped exclusions transform (applyWafExclusions/applyWafRateLimit429 from @everystack/server/cdn). Also: edge auth, response caching by auth state, epoch invalidation, and debugging edge 403s.',
+    filename: 'caching.md',
+  },
   {
     uri: 'everystack://expo-server-deploy',
     name: 'Deploying an Expo Router Server App',

package/src/resources/security.md

@@ -263,8 +263,8 @@ RESET ROLE;
 - [ ] Bcrypt cost >= 10
 
 ### Infrastructure
-- [ ] WAF managed rules (exclude SQLi_QUERYARGUMENTS on API paths for PostgREST syntax)
-- [ ] Rate limiting (1000 req/5 min per IP)
+- [ ] WAF managed rules — set the JSON-API false-positive BODY/HEADER rules (SQLi_BODY, SizeRestrictions_BODY, GenericRFI_BODY, Log4JRCE_HEADER) to COUNT via `applyWafExclusions`, or they 403 every PostgREST request. See everystack://caching (read BEFORE enabling `waf` on the Router).
+- [ ] Rate limiting — 429 not 403 (applyWafRateLimit429); ~2000 req/5 min per IP. See everystack://caching.
 - [ ] CloudFront edge JWT verification for latency-sensitive paths
 - [ ] Database credentials via SST Resource linking
 - [ ] No debug endpoints or env dumps in production