@everystack/mcp 0.4.0 → 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

@@ -5,6 +5,8 @@
 ## When to Use
 Read this when deploying an everystack app to AWS for the first time or adding a new stage.
 
+If your app.json has `web.output: "server"` (SSR pages or `+api.ts` routes — most Expo Router apps), read everystack://expo-server-deploy next: it covers what deploys where for that shape, including where your `+api.ts` routes run.
+
 ## Prerequisites
 
 - Node.js 20+, pnpm
@@ -57,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

@@ -0,0 +1,217 @@
+# Deploying an Expo Router Server App
+
+> How `web.output: "server"` maps to AWS: what deploys where, where your `+api.ts` routes run, and where the everystack handler sits among them.
+
+## When to Use
+
+Read this when your app.json has `web.output: "server"` (SSR pages, `+api.ts` API routes) and you are deploying to AWS. This is the deploy chapter for the most common Expo Router app shape — if your app is fully static (`web.output: "static"`), everystack://deployment alone is enough.
+
+## The Two-Deployable Model
+
+The single most important fact: **the Expo server export is NOT the Lambda handler.** There are two deployables with two verbs:
+
+| Deployable | Contains | Verb | Frequency |
+|---|---|---|---|
+| Infrastructure + entrypoints | VPC, RDS, buckets, Router, the Lambda entry files in `server/` | `sst deploy` | Rarely (infra changes) |
+| App code | Your entire Expo export: SSR pages, ALL `+api.ts` routes, client bundles | `everystack update --channel <name>` | Every ship (same verb as OTA) |
+
+`everystack update` runs the expo export and publishes it as a compressed archive to the Updates bucket. At runtime, the Lambda's SSR fallback downloads that archive to `/tmp` (cached across warm invocations) and serves it with `expo-server` — Expo's own server runtime. Your app code never gets bundled into the Lambda; it ships like an OTA update.
+
+## Request Flow
+
+```
+CloudFront Router
+  └─ Api Lambda (server/api.ts — createPluginLambdaHandler)
+       ├─ plugin routes claim their paths first (e.g. /api → everystack handler)
+       └─ everything else → ssrPlugin fallback → expo-server runs YOUR export:
+            ├─ SSR pages (with loader())
+            └─ your +api.ts routes (mcp+api.ts, app/games/[id]+api.ts, ...)
+```
+
+**Your `+api.ts` routes ship and serve as-is.** They ride the published bundle and expo-server dispatches to them inside the Lambda. Nothing has to be collapsed into the everystack handler.
+
+## The Lambda Entrypoint
+
+```typescript
+// server/api.ts — the Function handler for `sst deploy`
+import { createPluginLambdaHandler, ssrPlugin } from '@everystack/server/plugin';
+import { createAppContext, appPlugins } from './context';
+
+export const handler = createPluginLambdaHandler({
+  context: () => createAppContext(),
+  plugins: appPlugins,
+  fallback: ssrPlugin(),   // serves the published Expo export: SSR + your +api.ts routes
+});
+```
+
+## One Plugin List, Two Venues
+
+Define your plugins once; mount them in both places. Locally, Expo Router serves them through a catch-all route. Deployed, the Lambda mounts the same list and claims those paths BEFORE the fallback — so the deployed `/api` runs with SST Resource linking, never the bundle's copy.
+
+```typescript
+// server/context.ts — shared by local dev and every Lambda
+import { createDb } from '@everystack/server/db';
+import { apiPlugin } from './plugins/api';       // your everystack createHandler, as a plugin
+import { authPlugin } from '@everystack/auth/plugin';
+import { schema } from '../db';
+
+export async function createAppContext() {
+  const { db } = createDb(schema);   // Resource-linked on Lambda, DATABASE_URL locally
+  return { db, schema, environment: process.env.ENVIRONMENT ?? 'dev', /* verifyToken, ... */ };
+}
+
+export const appPlugins = [authPlugin, apiPlugin];
+```
+
+```typescript
+// server/plugins/api.ts — the everystack handler as ONE plugin among your routes
+import { createHandler } from '@everystack/api';
+
+export async function apiPlugin(ctx) {
+  const handler = createHandler(ctx.db, ctx.schema, { basePath: '/api', /* options */ });
+  return { routes: [{ path: '/api', handler }] };
+}
+```
+
+```typescript
+// app/api/[...path]+api.ts — LOCAL DEV venue (Expo Router serves this; the
+// deployed Lambda claims /api first, so this copy never runs in production)
+import { createPluginHandler } from '@everystack/server/plugin';
+import { createAppContext, appPlugins } from '../../server/context';
+
+const handler = createPluginHandler({ context: createAppContext, plugins: appPlugins });
+export const GET = handler; export const POST = handler;
+export const PATCH = handler; export const DELETE = handler;
+```
+
+Your OTHER `+api.ts` routes (`app/mcp+api.ts`, `app/games/[id]+api.ts`, ...) need no counterpart: local dev serves them directly, deployed they serve through the fallback.
+
+## The Ops Entrypoint (db:migrate, db:seed, console)
+
+`everystack db:migrate` invokes a dedicated, privileged Lambda over IAM — it has no public URL and holds the operator credential so the API Lambda never does.
+
+```typescript
+// server/ops.ts
+import { Resource } from 'sst';
+import { createPluginLambdaHandler, dbPlugin } from '@everystack/server/plugin';
+import { createAppContext, appPlugins } from './context';
+
+export const handler = createPluginLambdaHandler({
+  http: false,   // actions-only: rejects HTTP, answers IAM invokes
+  context: () => createAppContext({ admin: true }),
+  plugins: [
+    ...appPlugins,
+    dbPlugin({
+      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).
+    }),
+  ],
+});
+```
+
+## Minimal sst.config.ts
+
+The complete infrastructure for this app shape (V2: server app + PostgreSQL). Copy, rename, deploy.
+
+```typescript
+/// <reference path="./.sst/platform/config.d.ts" />
+export default $config({
+  app(input) {
+    return {
+      name: 'my-app',
+      removal: input?.stage === 'production' ? 'retain' : 'remove',
+      home: 'aws',
+    };
+  },
+  async run() {
+    const vpc = new sst.aws.Vpc('Vpc');
+    const database = new sst.aws.Postgres('Database', {
+      vpc,
+      // Local dev: `sst dev` uses this instead of RDS
+      dev: { host: 'localhost', port: 5432, username: 'postgres', password: 'postgres', database: 'my_app_dev' },
+    });
+
+    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`.
+    const databaseUrl = new sst.Secret('DATABASE_URL');
+
+    const router = new sst.aws.Router('Router', {
+      // Custom domain: Route 53 is the default DNS adapter. With your zone
+      // delegated to Route 53, this one line provisions the ACM certificate
+      // and DNS records automatically.
+      domain: $app.stage === 'production'
+        ? 'my-app.com'
+        : `${$app.stage}.my-app.com`,
+    });
+
+    const api = new sst.aws.Function('Api', {
+      handler: 'server/api.handler',
+      runtime: 'nodejs20.x',
+      timeout: '30 seconds',
+      vpc,
+      link: [databaseUrl, updates, clientBundles, jwtSecret],
+      url: { router: { instance: router, path: '/' } },
+      environment: { ENVIRONMENT: $app.stage, SITE_URL: router.url },
+    });
+
+    const ops = new sst.aws.Function('Ops', {
+      handler: 'server/ops.handler',
+      runtime: 'nodejs20.x',
+      timeout: '120 seconds',
+      vpc,
+      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. 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,
+    };
+  },
+});
+```
+
+## Local vs Deployed Database Connection
+
+`createDb()` from `@everystack/server/db` serves both venues with one code path (requires `@everystack/server` >= 0.4.4):
+
+- **Deployed:** the linked `DATABASE_URL` secret resolves via SST Resource; TLS defaults to `require` (RDS).
+- **Local:** set `DATABASE_URL=postgres://user@localhost:5432/my_app_dev?sslmode=disable`. An explicit `sslmode` in the URL wins; the handler code does not change.
+
+Do not hand-build a `postgres()` client from env vars to escape TLS — the URL is the contract.
+
+## Deploy Loop
+
+```bash
+sst deploy --stage dev                       # infrastructure + entrypoints (rare)
+everystack db:provision --stage dev          # mint the least-privilege API credential (once per stage)
+everystack update --channel dev              # export + publish the app code (every ship)
+everystack db:migrate --stage dev            # run migrations via the ops Lambda
+everystack db:seed --stage dev               # dev only
+```
+
+Subsequent app-code ships are `everystack update` alone — no `sst deploy`, no Lambda redeploy.
+
+## Gotchas
+
+- **Nothing serves until the first `everystack update`** — the fallback has no bundle to download yet, so `/` returns 404 while `/api` (plugin-claimed) already works.
+- **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,18 @@ 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",
+    description: 'How web.output:"server" maps to AWS: the two-deployable model (sst deploy vs everystack update), where +api.ts routes run (the SSR fallback serves the published bundle), the one-plugin-list/two-venues pattern (local catch-all route + deployed Lambda entrypoint), the ops entrypoint for db:migrate, custom domains on the Router, and the local-vs-deployed database URL (sslmode). Read this when deploying any Expo Router app with SSR or +api.ts routes.',
+    filename: "expo-server-deploy.md"
+  },
   {
     uri: "everystack://admin",
     name: "Admin Dashboard",
@@ -22472,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",
@@ -22613,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`",
@@ -22916,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",
@@ -23717,7 +23733,7 @@ async function runGovernanceCli(argv) {
 }
 
 // src/index.ts
-var version2 = (true ? "0.4.0" : 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.0",
+  "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.2",
-    "@everystack/model": "0.4.1"
+    "@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

@@ -5,6 +5,8 @@
 ## When to Use
 Read this when deploying an everystack app to AWS for the first time or adding a new stage.
 
+If your app.json has `web.output: "server"` (SSR pages or `+api.ts` routes — most Expo Router apps), read everystack://expo-server-deploy next: it covers what deploys where for that shape, including where your `+api.ts` routes run.
+
 ## Prerequisites
 
 - Node.js 20+, pnpm
@@ -57,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

@@ -0,0 +1,217 @@
+# Deploying an Expo Router Server App
+
+> How `web.output: "server"` maps to AWS: what deploys where, where your `+api.ts` routes run, and where the everystack handler sits among them.
+
+## When to Use
+
+Read this when your app.json has `web.output: "server"` (SSR pages, `+api.ts` API routes) and you are deploying to AWS. This is the deploy chapter for the most common Expo Router app shape — if your app is fully static (`web.output: "static"`), everystack://deployment alone is enough.
+
+## The Two-Deployable Model
+
+The single most important fact: **the Expo server export is NOT the Lambda handler.** There are two deployables with two verbs:
+
+| Deployable | Contains | Verb | Frequency |
+|---|---|---|---|
+| Infrastructure + entrypoints | VPC, RDS, buckets, Router, the Lambda entry files in `server/` | `sst deploy` | Rarely (infra changes) |
+| App code | Your entire Expo export: SSR pages, ALL `+api.ts` routes, client bundles | `everystack update --channel <name>` | Every ship (same verb as OTA) |
+
+`everystack update` runs the expo export and publishes it as a compressed archive to the Updates bucket. At runtime, the Lambda's SSR fallback downloads that archive to `/tmp` (cached across warm invocations) and serves it with `expo-server` — Expo's own server runtime. Your app code never gets bundled into the Lambda; it ships like an OTA update.
+
+## Request Flow
+
+```
+CloudFront Router
+  └─ Api Lambda (server/api.ts — createPluginLambdaHandler)
+       ├─ plugin routes claim their paths first (e.g. /api → everystack handler)
+       └─ everything else → ssrPlugin fallback → expo-server runs YOUR export:
+            ├─ SSR pages (with loader())
+            └─ your +api.ts routes (mcp+api.ts, app/games/[id]+api.ts, ...)
+```
+
+**Your `+api.ts` routes ship and serve as-is.** They ride the published bundle and expo-server dispatches to them inside the Lambda. Nothing has to be collapsed into the everystack handler.
+
+## The Lambda Entrypoint
+
+```typescript
+// server/api.ts — the Function handler for `sst deploy`
+import { createPluginLambdaHandler, ssrPlugin } from '@everystack/server/plugin';
+import { createAppContext, appPlugins } from './context';
+
+export const handler = createPluginLambdaHandler({
+  context: () => createAppContext(),
+  plugins: appPlugins,
+  fallback: ssrPlugin(),   // serves the published Expo export: SSR + your +api.ts routes
+});
+```
+
+## One Plugin List, Two Venues
+
+Define your plugins once; mount them in both places. Locally, Expo Router serves them through a catch-all route. Deployed, the Lambda mounts the same list and claims those paths BEFORE the fallback — so the deployed `/api` runs with SST Resource linking, never the bundle's copy.
+
+```typescript
+// server/context.ts — shared by local dev and every Lambda
+import { createDb } from '@everystack/server/db';
+import { apiPlugin } from './plugins/api';       // your everystack createHandler, as a plugin
+import { authPlugin } from '@everystack/auth/plugin';
+import { schema } from '../db';
+
+export async function createAppContext() {
+  const { db } = createDb(schema);   // Resource-linked on Lambda, DATABASE_URL locally
+  return { db, schema, environment: process.env.ENVIRONMENT ?? 'dev', /* verifyToken, ... */ };
+}
+
+export const appPlugins = [authPlugin, apiPlugin];
+```
+
+```typescript
+// server/plugins/api.ts — the everystack handler as ONE plugin among your routes
+import { createHandler } from '@everystack/api';
+
+export async function apiPlugin(ctx) {
+  const handler = createHandler(ctx.db, ctx.schema, { basePath: '/api', /* options */ });
+  return { routes: [{ path: '/api', handler }] };
+}
+```
+
+```typescript
+// app/api/[...path]+api.ts — LOCAL DEV venue (Expo Router serves this; the
+// deployed Lambda claims /api first, so this copy never runs in production)
+import { createPluginHandler } from '@everystack/server/plugin';
+import { createAppContext, appPlugins } from '../../server/context';
+
+const handler = createPluginHandler({ context: createAppContext, plugins: appPlugins });
+export const GET = handler; export const POST = handler;
+export const PATCH = handler; export const DELETE = handler;
+```
+
+Your OTHER `+api.ts` routes (`app/mcp+api.ts`, `app/games/[id]+api.ts`, ...) need no counterpart: local dev serves them directly, deployed they serve through the fallback.
+
+## The Ops Entrypoint (db:migrate, db:seed, console)
+
+`everystack db:migrate` invokes a dedicated, privileged Lambda over IAM — it has no public URL and holds the operator credential so the API Lambda never does.
+
+```typescript
+// server/ops.ts
+import { Resource } from 'sst';
+import { createPluginLambdaHandler, dbPlugin } from '@everystack/server/plugin';
+import { createAppContext, appPlugins } from './context';
+
+export const handler = createPluginLambdaHandler({
+  http: false,   // actions-only: rejects HTTP, answers IAM invokes
+  context: () => createAppContext({ admin: true }),
+  plugins: [
+    ...appPlugins,
+    dbPlugin({
+      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).
+    }),
+  ],
+});
+```
+
+## Minimal sst.config.ts
+
+The complete infrastructure for this app shape (V2: server app + PostgreSQL). Copy, rename, deploy.
+
+```typescript
+/// <reference path="./.sst/platform/config.d.ts" />
+export default $config({
+  app(input) {
+    return {
+      name: 'my-app',
+      removal: input?.stage === 'production' ? 'retain' : 'remove',
+      home: 'aws',
+    };
+  },
+  async run() {
+    const vpc = new sst.aws.Vpc('Vpc');
+    const database = new sst.aws.Postgres('Database', {
+      vpc,
+      // Local dev: `sst dev` uses this instead of RDS
+      dev: { host: 'localhost', port: 5432, username: 'postgres', password: 'postgres', database: 'my_app_dev' },
+    });
+
+    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`.
+    const databaseUrl = new sst.Secret('DATABASE_URL');
+
+    const router = new sst.aws.Router('Router', {
+      // Custom domain: Route 53 is the default DNS adapter. With your zone
+      // delegated to Route 53, this one line provisions the ACM certificate
+      // and DNS records automatically.
+      domain: $app.stage === 'production'
+        ? 'my-app.com'
+        : `${$app.stage}.my-app.com`,
+    });
+
+    const api = new sst.aws.Function('Api', {
+      handler: 'server/api.handler',
+      runtime: 'nodejs20.x',
+      timeout: '30 seconds',
+      vpc,
+      link: [databaseUrl, updates, clientBundles, jwtSecret],
+      url: { router: { instance: router, path: '/' } },
+      environment: { ENVIRONMENT: $app.stage, SITE_URL: router.url },
+    });
+
+    const ops = new sst.aws.Function('Ops', {
+      handler: 'server/ops.handler',
+      runtime: 'nodejs20.x',
+      timeout: '120 seconds',
+      vpc,
+      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. 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,
+    };
+  },
+});
+```
+
+## Local vs Deployed Database Connection
+
+`createDb()` from `@everystack/server/db` serves both venues with one code path (requires `@everystack/server` >= 0.4.4):
+
+- **Deployed:** the linked `DATABASE_URL` secret resolves via SST Resource; TLS defaults to `require` (RDS).
+- **Local:** set `DATABASE_URL=postgres://user@localhost:5432/my_app_dev?sslmode=disable`. An explicit `sslmode` in the URL wins; the handler code does not change.
+
+Do not hand-build a `postgres()` client from env vars to escape TLS — the URL is the contract.
+
+## Deploy Loop
+
+```bash
+sst deploy --stage dev                       # infrastructure + entrypoints (rare)
+everystack db:provision --stage dev          # mint the least-privilege API credential (once per stage)
+everystack update --channel dev              # export + publish the app code (every ship)
+everystack db:migrate --stage dev            # run migrations via the ops Lambda
+everystack db:seed --stage dev               # dev only
+```
+
+Subsequent app-code ships are `everystack update` alone — no `sst deploy`, no Lambda redeploy.
+
+## Gotchas
+
+- **Nothing serves until the first `everystack update`** — the fallback has no bundle to download yet, so `/` returns 404 while `/api` (plugin-claimed) already works.
+- **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,20 @@ 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',
+    description:
+      'How web.output:"server" maps to AWS: the two-deployable model (sst deploy vs everystack update), where +api.ts routes run (the SSR fallback serves the published bundle), the one-plugin-list/two-venues pattern (local catch-all route + deployed Lambda entrypoint), the ops entrypoint for db:migrate, custom domains on the Router, and the local-vs-deployed database URL (sslmode). Read this when deploying any Expo Router app with SSR or +api.ts routes.',
+    filename: 'expo-server-deploy.md',
+  },
   {
     uri: 'everystack://admin',
     name: 'Admin Dashboard',

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