@everystack/server 0.1.1 → 0.2.1

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@everystack/server",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "Server runtime primitives for Lambda — event adapters, routing, SSR, image processing",
-  "license": "MIT",
+  "license": "AGPL-3.0-only",
   "publishConfig": {
     "access": "public"
   },
@@ -11,7 +11,6 @@
     "stubs",
     "README.md"
   ],
-  "type": "module",
   "exports": {
     ".": {
       "types": "./src/index.ts",
@@ -41,20 +40,33 @@
       "types": "./src/stubs.ts",
       "default": "./src/stubs.ts"
     },
+    "./plugin": {
+      "types": "./src/plugin.ts",
+      "default": "./src/plugin.ts"
+    },
     "./cdn": {
       "types": "./src/cdn/index.ts",
       "default": "./src/cdn/index.ts"
+    },
+    "./kvs": {
+      "types": "./src/kvs.ts",
+      "default": "./src/kvs.ts"
     }
   },
+  "scripts": {
+    "test": "jest",
+    "build": "tsc --build",
+    "lint": "tsc --noEmit"
+  },
   "peerDependencies": {
-    "@aws-sdk/client-s3": ">=3.0.0",
-    "@aws-sdk/s3-request-presigner": ">=3.0.0",
+    "@aws-sdk/client-s3": "3.1045.0",
+    "@aws-sdk/s3-request-presigner": "3.1045.0",
     "@everystack/auth": ">=0.1.0",
     "@everystack/cli": ">=0.1.0",
-    "drizzle-orm": ">=0.30.0",
-    "postgres": ">=3.0.0",
-    "sharp": ">=0.33.0",
-    "sst": ">=3.0.0"
+    "drizzle-orm": "0.41.0",
+    "postgres": "3.4.9",
+    "sharp": "0.34.5",
+    "sst": "4.13.1"
   },
   "peerDependenciesMeta": {
     "sst": {
@@ -77,21 +89,16 @@
     }
   },
   "devDependencies": {
-    "@types/aws-lambda": "^8.10.145",
-    "@types/jest": "^29.5.14",
-    "@types/node": "^22.0.0",
-    "drizzle-orm": "^0.41.0",
-    "jest": "^29.7.0",
-    "postgres": "^3.4.0",
-    "sst": "^4.13.1",
-    "ts-jest": "^29.3.0",
-    "typescript": "^5.7.0",
-    "@everystack/auth": "0.1.0",
-    "@everystack/cli": "0.1.0"
-  },
-  "scripts": {
-    "test": "NODE_OPTIONS='--experimental-vm-modules' jest",
-    "build": "tsc --build",
-    "lint": "tsc --noEmit"
+    "@everystack/auth": "workspace:*",
+    "@everystack/cli": "workspace:*",
+    "@types/aws-lambda": "8.10.161",
+    "@types/jest": "29.5.14",
+    "@types/node": "22.19.18",
+    "drizzle-orm": "0.41.0",
+    "jest": "29.7.0",
+    "postgres": "3.4.9",
+    "sst": "4.13.1",
+    "ts-jest": "29.4.9",
+    "typescript": "5.9.3"
   }
-}
+}

package/src/cdn/compose.ts

@@ -72,6 +72,9 @@ export function composeViewerRequest(opts: ComposeOptions): ComposeResult {
   }
 
   // 2. Emit state as namespaced vars.
+  // SECURITY: State values originate from developer configuration (e.g., HandlerOptions,
+  // SST config), not from end-user input. JSON.stringify safely serializes these values.
+  // If state sources ever include user-controlled data, this interpolation must be revisited.
   const stateLines: string[] = [];
   for (const f of features) {
     if (!f.state) continue;

package/src/cdn/features.ts

@@ -13,34 +13,34 @@ import type { Feature } from './compose';
 
 // ---------- auth ----------
 
-export type Role = string;
-
-export interface AuthRoleEntry {
-  /** Read role required (GET/HEAD). */
-  r: Role;
-  /** Write role required (POST/PUT/PATCH/DELETE). */
-  w: Role;
-}
-
 export interface AuthFeatureOptions {
   /** HS256 secret — same secret your Lambda mints with. */
   secret: string;
   /**
-   * Path prefixes that bypass auth entirely. Default:
-   * ['/api/auth/', '/api/health', '/api/updates', '/api/storage/public'].
-   */
-  publicPaths?: string[];
-  /**
-   * Optional role table. Keyed by table name extracted from /api/<table>/...
-   * Use '*' for default. Requires `tableFromPath: true`.
+   * Paths that require authentication. Prefix with `!` to negate (exempt).
+   * Longest matching prefix wins. Paths with no match are public.
+   *
+   * @example
+   * ```ts
+   * requireAuth: ['/api/', '!/api/auth/', '!/api/health']
+   * ```
+   * - `/api/*`        — requires JWT
+   * - `/api/auth/*`   — public (exempted, longer match wins)
+   * - `/api/health`   — public (exempted, longer match wins)
+   * - `/`, `/about`   — public (no matching rule)
    */
-  roles?: Record<string, AuthRoleEntry>;
-  /** Role hierarchy, weakest first. Required when `roles` is set. */
-  roleHierarchy?: Role[];
+  requireAuth: string[];
   /**
-   * Extract table name from `/api/<table>/...` for role lookup. Default false.
+   * HTTP methods that bypass auth on protected paths.
+   * Aligns with the handler's `publicRoutes` option so the edge and Lambda
+   * share the same "reads are public" semantics.
+   *
+   * @example
+   * ```ts
+   * publicMethods: ['GET', 'HEAD']
+   * ```
    */
-  tableFromPath?: boolean;
+  publicMethods?: string[];
   /** Allowed clock skew (seconds). Default 30. */
   clockSkewSec?: number;
   /**
@@ -58,28 +58,22 @@ export interface AuthFeatureOptions {
   order?: number;
 }
 
-const DEFAULT_AUTH_PUBLIC = [
-  '/api/auth/',
-  '/api/health',
-  '/api/updates',
-  '/api/storage/public',
-];
-
 export function authFeature(opts: AuthFeatureOptions): Feature {
-  const publicPaths = opts.publicPaths ?? DEFAULT_AUTH_PUBLIC;
-  const roles = opts.roles ?? null;
-  const hierarchy = opts.roleHierarchy ?? null;
-  const tableFromPath = opts.tableFromPath === true;
   const cookieName = opts.cookieName !== false ? (opts.cookieName ?? '__es_token') : '';
 
-  if (roles && !hierarchy) {
-    throw new Error('authFeature: roleHierarchy is required when roles is set');
-  }
-
   const verifierSrc = opts.compact
     ? generateCompactCffVerifier({ clockSkewSec: opts.clockSkewSec })
     : generateCffVerifier({ clockSkewSec: opts.clockSkewSec });
 
+  // Parse requireAuth entries: '!' prefix = negated (exempt from auth).
+  // Sort by path length descending so longest (most specific) prefix wins.
+  const rules = opts.requireAuth.map(entry => {
+    const negated = entry.startsWith('!');
+    const path = negated ? entry.slice(1) : entry;
+    return { path, auth: !negated };
+  });
+  rules.sort((a, b) => b.path.length - a.path.length);
+
   // Cookie fallback block — only emitted when cookieName is set.
   const cookieBlock = cookieName
     ? `
@@ -99,49 +93,35 @@ export function authFeature(opts: AuthFeatureOptions): Feature {
     },
     state: {
       secret: opts.secret,
-      publicPaths,
-      roles: roles ?? {},
-      hierarchy: hierarchy ?? [],
-      tableFromPath,
+      rulePaths: rules.map(r => r.path),
+      ruleAuth: rules.map(r => r.auth),
+      publicMethods: opts.publicMethods ?? [],
       cookieName,
     },
     body: `
-function __auth_isPublic(uri) {
-  for (var i = 0; i < __auth_publicPaths.length; i++) {
-    var p = __auth_publicPaths[i];
-    if (uri === p || uri.indexOf(p) === 0) return true;
+function __auth_needsAuth(uri) {
+  for (var i = 0; i < __auth_rulePaths.length; i++) {
+    var p = __auth_rulePaths[i];
+    if (uri === p || uri.indexOf(p) === 0) return __auth_ruleAuth[i];
   }
   return false;
 }
-function __auth_roleLevel(role) {
-  for (var i = 0; i < __auth_hierarchy.length; i++) {
-    if (__auth_hierarchy[i] === role) return i;
-  }
-  return -1;
-}
-function __auth_required(uri, method) {
-  if (!__auth_tableFromPath) return null;
-  var m = uri.match(/^\\/api\\/([^\\/?]+)/);
-  if (!m) return 'public';
-  var entry = __auth_roles[m[1]] || __auth_roles['*'];
-  if (!entry) return null;
-  return (method === 'GET' || method === 'HEAD') ? entry.r : entry.w;
-}
 function __auth_reject(status, message) {
   return { statusCode: status, statusDescription: status === 401 ? 'Unauthorized' : 'Forbidden', headers: { 'content-type': { value: 'application/json' }, 'cache-control': { value: 'no-store' } }, body: { encoding: 'text', data: JSON.stringify({ message: message }) } };
 }
 var __auth_req = event.request;
 var __auth_uri = __auth_req.uri;
-var __auth_method = __auth_req.method;
-var __auth_reqRole = __auth_required(__auth_uri, __auth_method);
-if (!__auth_isPublic(__auth_uri) && __auth_reqRole !== 'public') {
-  var __auth_h = __auth_req.headers.authorization && __auth_req.headers.authorization.value;${cookieBlock}
-  if (!__auth_h || __auth_h.indexOf('Bearer ') !== 0) return __auth_reject(401, 'Authentication required');
-  var __auth_claims = verifyJwt(__auth_h.slice(7), __auth_secret);
-  if (!__auth_claims) return __auth_reject(401, 'Invalid or expired token');
-  if (__auth_reqRole && __auth_reqRole !== 'authenticated') {
-    var __auth_userRole = __auth_claims.role || 'authenticated';
-    if (__auth_roleLevel(__auth_userRole) < __auth_roleLevel(__auth_reqRole)) return __auth_reject(403, 'Insufficient role');
+if (__auth_needsAuth(__auth_uri)) {
+  var __auth_m = __auth_req.method;
+  var __auth_pub = false;
+  for (var __auth_mi = 0; __auth_mi < __auth_publicMethods.length; __auth_mi++) {
+    if (__auth_m === __auth_publicMethods[__auth_mi]) { __auth_pub = true; break; }
+  }
+  if (!__auth_pub) {
+    var __auth_h = __auth_req.headers.authorization && __auth_req.headers.authorization.value;${cookieBlock}
+    if (!__auth_h || __auth_h.indexOf('Bearer ') !== 0) return __auth_reject(401, 'Authentication required');
+    var __auth_claims = verifyJwt(__auth_h.slice(7), __auth_secret);
+    if (!__auth_claims) return __auth_reject(401, 'Invalid or expired token');
   }
 }
 `,
@@ -182,6 +162,70 @@ if (__geo_country && __geo_blocked.length) {
   };
 }
 
+// ---------- cache-version ----------
+
+export interface CacheVersionFeatureOptions {
+  /**
+   * URI prefix → scope name mapping. When a request URI matches a prefix,
+   * the corresponding scope epoch (`__epoch__:<scope>`) is checked in KVS.
+   *
+   * @example
+   * ```ts
+   * scopes: { '/api/': 'api', '/media/': 'media' }
+   * ```
+   * Requests to `/api/posts` check `__epoch__:api`, `/media/img.jpg` checks
+   * `__epoch__:media`, all others check `__epoch__:<defaultScope>`.
+   */
+  scopes?: Record<string, string>;
+  /** Scope for URIs that don't match any prefix. Default `'web'`. */
+  defaultScope?: string;
+  /** Override `order`. Default 10 (early — set cache key before auth). */
+  order?: number;
+}
+
+/**
+ * KVS-based cache versioning at the CloudFront edge.
+ *
+ * Reads three version layers from KVS and picks the highest:
+ *   1. Global epoch (`__epoch__`)
+ *   2. Scope epoch (`__epoch__:<scope>`) based on URI prefix
+ *   3. Per-path epoch (the URI itself)
+ *
+ * Sets `?_v=<version>` on the request querystring so CloudFront treats
+ * different versions as distinct cache keys.
+ *
+ * Requires `kvStore` to be set on the Router's `edge.viewerRequest`.
+ */
+export function cacheVersionFeature(opts: CacheVersionFeatureOptions = {}): Feature {
+  const scopes = opts.scopes ?? {};
+  const defaultScope = opts.defaultScope ?? 'web';
+  const prefixes = Object.keys(scopes);
+  const scopeNames = Object.values(scopes);
+
+  return {
+    name: 'cacheVersion',
+    order: opts.order ?? 10,
+    state: {
+      prefixes,
+      scopeNames,
+      defaultScope,
+    },
+    body: `
+var __cv_u = event.request.uri, __cv_q = event.request.querystring;
+var __cv_gv = "", __cv_nv = "", __cv_pv = "";
+try { __cv_gv = await cf.kvs().get("__epoch__") || ""; } catch(__cv_e) {}
+var __cv_scope = __cacheVersion_defaultScope;
+for (var __cv_i = 0; __cv_i < __cacheVersion_prefixes.length; __cv_i++) {
+  if (__cv_u.indexOf(__cacheVersion_prefixes[__cv_i]) === 0) { __cv_scope = __cacheVersion_scopeNames[__cv_i]; break; }
+}
+try { __cv_nv = await cf.kvs().get("__epoch__:" + __cv_scope) || ""; } catch(__cv_e) {}
+try { __cv_pv = await cf.kvs().get(__cv_u) || ""; } catch(__cv_e) {}
+var __cv_v = [__cv_gv, __cv_nv, __cv_pv].filter(function(x){return x;}).sort().pop() || "";
+if (__cv_v) __cv_q._v = { value: __cv_v };
+`,
+  };
+}
+
 // ---------- cache-key ----------
 
 export interface CacheKeyFeatureOptions {

package/src/cdn/index.ts

@@ -16,7 +16,7 @@
  */
 
 import { composeViewerRequest } from './compose';
-import { authFeature, type AuthFeatureOptions, type AuthRoleEntry, type Role } from './features';
+import { authFeature, type AuthFeatureOptions } from './features';
 
 export {
   composeViewerRequest,
@@ -29,24 +29,25 @@ export {
   authFeature,
   geoFeature,
   cacheKeyFeature,
+  cacheVersionFeature,
   type AuthFeatureOptions,
-  type AuthRoleEntry,
   type GeoFeatureOptions,
   type CacheKeyFeatureOptions,
-  type Role,
+  type CacheVersionFeatureOptions,
 } from './features';
+export {
+  stripSstDeadCode,
+  applyWafExclusions,
+  WAF_JSON_API_OVERRIDES,
+} from './transforms';
 
 // ---------- Back-compat: createAuthFunction ----------
 
-export interface RoleEntry extends AuthRoleEntry {}
-
 export interface AuthFunctionConfig {
   /** HS256 secret — same secret your Lambda uses to mint tokens. */
   secret: string;
-  publicPaths?: string[];
-  roles?: Record<string, RoleEntry>;
-  roleHierarchy?: Role[];
-  tableFromPath?: boolean;
+  /** Auth rules. Default: `['/']` (protect everything). See authFeature. */
+  requireAuth?: string[];
   clockSkewSec?: number;
   /** Cookie name for SSR auth fallback. Default: '__es_token'. Set false to disable. */
   cookieName?: string | false;
@@ -65,10 +66,7 @@ export interface AuthFunctionResult {
 export function createAuthFunction(config: AuthFunctionConfig): AuthFunctionResult {
   const opts: AuthFeatureOptions = {
     secret: config.secret,
-    publicPaths: config.publicPaths,
-    roles: config.roles,
-    roleHierarchy: config.roleHierarchy,
-    tableFromPath: config.tableFromPath,
+    requireAuth: config.requireAuth ?? ['/'],
     clockSkewSec: config.clockSkewSec,
     cookieName: config.cookieName,
   };

package/src/cdn/transforms.ts

@@ -0,0 +1,157 @@
+/**
+ * SST infrastructure transforms for the CDN layer.
+ *
+ * Utilities for $transform() callbacks in sst.config.ts. The $transform()
+ * call itself must stay in the app (it's an SST global), but the
+ * transformation logic lives here so every everystack app doesn't
+ * duplicate it.
+ */
+
+// ---------- Dead code stripping for CloudFront Functions ----------
+
+/**
+ * Strip a named function declaration from source code. Handles both
+ * `function name(` and `async function name(`. Tracks brace depth and
+ * skips string literals to find the matching closing brace.
+ *
+ * Returns code unchanged if the function isn't found (fail-safe).
+ */
+function stripFunction(code: string, name: string): string {
+  let start = code.indexOf('function ' + name + '(');
+  if (start === -1) return code;
+  // Include "async " prefix if present
+  if (start >= 6 && code.slice(start - 6, start) === 'async ') {
+    start -= 6;
+  }
+  let i = code.indexOf('{', start);
+  if (i === -1) return code;
+  let depth = 1;
+  i++;
+  while (i < code.length && depth > 0) {
+    const c = code[i];
+    if (c === '"' || c === "'" || c === '`') {
+      i++;
+      while (i < code.length && code[i] !== c) {
+        if (code[i] === '\\') i++;
+        i++;
+      }
+    } else if (c === '{') {
+      depth++;
+    } else if (c === '}') {
+      depth--;
+    }
+    i++;
+  }
+  return code.slice(0, start) + code.slice(i);
+}
+
+/**
+ * Strip dead SST-generated functions from CloudFront Function wrapper code.
+ *
+ * SST's Router includes `routeSite()` (~3KB) for Next.js/static-site routing
+ * with nested helpers (setNextjsGeoHeaders, setNextjsCacheKey, getHeader,
+ * findNearestServer, haversineDistance). Expo apps only use "url" and "bucket"
+ * route types, so routeSite is dead code. Stripping it reclaims ~3000 bytes
+ * toward the 10,240-byte CFF limit.
+ *
+ * Also removes the `if (route.type === "site")` call site that invokes
+ * the stripped function.
+ *
+ * @example
+ * ```ts
+ * // In sst.config.ts:
+ * import { stripSstDeadCode } from '@everystack/server/cdn';
+ *
+ * $transform(aws.cloudfront.Function, (args: any) => {
+ *   if (typeof args.code === 'string') {
+ *     args.code = stripSstDeadCode(args.code);
+ *   } else if (args.code?.apply) {
+ *     args.code = args.code.apply(stripSstDeadCode);
+ *   }
+ * });
+ * ```
+ */
+export function stripSstDeadCode(code: string): string {
+  const deadFunctions = ['routeSite'];
+  for (const name of deadFunctions) {
+    code = stripFunction(code, name);
+  }
+  // Remove the call site: if (route.type === "site") { ... await routeSite(...); ... }
+  code = code.replace(
+    /if \(route\.type === "site"\) \{[^}]*await routeSite\([^)]*\);[^}]*\}/g,
+    '',
+  );
+  return code;
+}
+
+// ---------- WAF rule exclusions ----------
+
+/**
+ * Default WAF rule exclusions for JSON APIs behind AWS Managed Rules.
+ *
+ * These rules commonly cause false positives on JSON request bodies:
+ *   - SizeRestrictions_BODY: large JSON payloads (admin bulk operations)
+ *   - GenericRFI_BODY: URLs in JSON values (avatarUrl, cdnUrl)
+ *   - SQLi_BODY: JSON keys resembling SQL keywords (limit, select, order)
+ *   - Log4JRCE_HEADER: JWT Authorization headers with encoded payloads
+ *
+ * Keys are AWS managed rule group names. Values are rule names to set to
+ * COUNT mode (log but don't block).
+ */
+export const WAF_JSON_API_OVERRIDES: Record<string, string[]> = {
+  AWSManagedRulesCommonRuleSet: ['SizeRestrictions_BODY', 'GenericRFI_BODY'],
+  AWSManagedRulesSQLiRuleSet: ['SQLi_BODY'],
+  AWSManagedRulesKnownBadInputsRuleSet: ['Log4JRCE_HEADER'],
+};
+
+/**
+ * Apply WAF rule exclusions by setting specific rules to COUNT mode.
+ *
+ * Takes a resolved rules array (from `$resolve(args.rules).apply(...)`)
+ * and returns the transformed array with the specified rule overrides.
+ *
+ * @param rules  Resolved WAF rules array from Pulumi.
+ * @param overrides  Rule group → rule names to set to COUNT. Defaults to
+ *                   {@link WAF_JSON_API_OVERRIDES}.
+ *
+ * @example
+ * ```ts
+ * // In sst.config.ts:
+ * import { applyWafExclusions } from '@everystack/server/cdn';
+ *
+ * $transform(aws.wafv2.WebAcl, (args: any) => {
+ *   if (!args.rules) return;
+ *   args.rules = $resolve(args.rules).apply(applyWafExclusions);
+ * });
+ * ```
+ */
+export function applyWafExclusions(
+  rules: any[],
+  overrides: Record<string, string[]> = WAF_JSON_API_OVERRIDES,
+): any[] {
+  // Build the override map in the shape WAF expects.
+  const ruleOverrides: Record<string, Array<{ name: string; actionToUse: { count: Record<string, never> } }>> = {};
+  for (const [group, ruleNames] of Object.entries(overrides)) {
+    ruleOverrides[group] = ruleNames.map((name) => ({
+      name,
+      actionToUse: { count: {} },
+    }));
+  }
+
+  return rules.map((rule: any) => {
+    const groupName = rule.statement?.managedRuleGroupStatement?.name;
+    if (groupName && ruleOverrides[groupName]) {
+      return {
+        ...rule,
+        statement: {
+          ...rule.statement,
+          managedRuleGroupStatement: {
+            ...rule.statement.managedRuleGroupStatement,
+            ruleActionOverrides: ruleOverrides[groupName],
+          },
+        },
+      };
+    }
+    return rule;
+  });
+}

package/src/db.ts

@@ -1,3 +1,4 @@
+/// <reference path="./sst-env.d.ts" />
 /**
  * @everystack/server/db — SST Resource-linked database helpers.
  *

package/src/image.ts

@@ -26,6 +26,12 @@ export interface ImageHandlerConfig {
   /** Cache-Control for image responses.
    *  Default: 'public, max-age=60, s-maxage=2592000, stale-while-revalidate=5' */
   cacheControl?: string;
+  /**
+   * Optional key validator. Called before fetching from S3.
+   * Return true to allow the request, false to reject with 403.
+   * Use this to verify the key exists in your database or matches an allowed prefix.
+   */
+  validateKey?: (key: string) => boolean | Promise<boolean>;
 }
 
 export interface TransformParams {
@@ -142,7 +148,7 @@ export async function processImage(
 export function createImageHandler(
   config: ImageHandlerConfig
 ): (event: APIGatewayProxyEventV2) => Promise<APIGatewayProxyStructuredResultV2> {
-  const { bucket, pathPrefix = '/media/' } = config;
+  const { bucket, pathPrefix = '/media/', validateKey } = config;
   const region = config.region || process.env.AWS_REGION;
 
   return async (event: APIGatewayProxyEventV2): Promise<APIGatewayProxyStructuredResultV2> => {
@@ -159,6 +165,27 @@ export function createImageHandler(
         };
       }
 
+      // Block path traversal attempts
+      if (key.includes('..') || key.startsWith('/')) {
+        return {
+          statusCode: 403,
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ error: 'Forbidden' }),
+        };
+      }
+
+      // Optional key validation (e.g. verify key exists in database)
+      if (validateKey) {
+        const allowed = await validateKey(key);
+        if (!allowed) {
+          return {
+            statusCode: 403,
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ error: 'Forbidden' }),
+          };
+        }
+      }
+
       const params = parseParams(event.queryStringParameters || {});
 
       const { S3Client, GetObjectCommand } = await import('@aws-sdk/client-s3');

package/src/index.ts

@@ -6,6 +6,8 @@
  * - createRouter — path-based request dispatch
  * - createLambdaHandler — full handler with lazy init, routing, error handling
  * - log — structured JSON logging
+ *
+ * For the plugin-based composition API, import from '@everystack/server/plugin'.
  */
 
 import type {

package/src/kvs.ts

@@ -0,0 +1,50 @@
+/**
+ * CloudFront KeyValueStore cache invalidation utility.
+ *
+ * Writes a timestamp to KVS keys, signaling CloudFront Functions
+ * to treat cached responses as stale. Used by both the events
+ * listener (wildcard callback) and worker (RPC dispatch).
+ *
+ * Usage:
+ *   import { invalidateKvsPaths } from '@everystack/server/kvs';
+ *   await invalidateKvsPaths(kvsArn, ['/api/posts', '/api/profiles']);
+ */
+
+/**
+ * Write a fresh timestamp to each KVS path, invalidating CloudFront caches.
+ *
+ * Each put changes the ETag, so we re-describe after each write.
+ * Dynamically imports AWS SDK to avoid bundling when unused.
+ */
+export async function invalidateKvsPaths(kvsArn: string, paths: string[]): Promise<void> {
+  if (!kvsArn || paths.length === 0) return;
+
+  await import('@aws-sdk/signature-v4a');
+  const {
+    CloudFrontKeyValueStoreClient,
+    DescribeKeyValueStoreCommand,
+    PutKeyCommand,
+  } = await import('@aws-sdk/client-cloudfront-keyvaluestore');
+
+  const client = new CloudFrontKeyValueStoreClient({});
+  const desc = await client.send(
+    new DescribeKeyValueStoreCommand({ KvsARN: kvsArn })
+  );
+  let etag = desc.ETag!;
+
+  for (const path of paths) {
+    await client.send(
+      new PutKeyCommand({
+        KvsARN: kvsArn,
+        Key: path,
+        Value: String(Math.floor(Date.now() / 1000)),
+        IfMatch: etag,
+      })
+    );
+    // KVS etag changes after each put — re-describe for next iteration
+    const newDesc = await client.send(
+      new DescribeKeyValueStoreCommand({ KvsARN: kvsArn })
+    );
+    etag = newDesc.ETag!;
+  }
+}

package/src/plugin.ts

@@ -0,0 +1,517 @@
+/**
+ * @everystack/server/plugin — Plugin system for composable Lambda handlers.
+ *
+ * Plugins are factory functions that receive a shared context and return
+ * route/action/handler contributions. The framework composes them into a
+ * single Lambda handler with lazy initialization.
+ */
+
+import type { Handler, Route, LogSink, ServerCacheConfig } from './index';
+import type {
+  APIGatewayProxyEventV2,
+  APIGatewayProxyStructuredResultV2,
+} from 'aws-lambda';
+import {
+  createRouter,
+  eventToRequest,
+  responseToResult,
+  log,
+} from './index';
+
+// --- Plugin Types ---
+
+/**
+ * Shared context provided to all plugins during initialization.
+ * Apps extend this with additional resources (auth handlers, job adapters, etc.).
+ */
+export interface PluginContext {
+  /** Drizzle database connection */
+  db: any;
+  /** App schema (all tables) */
+  schema: Record<string, any>;
+  /** Shared JWT verification — one function, used by all plugins */
+  verifyToken: (token: string) => Promise<Record<string, unknown> | null>;
+  /** Runtime environment */
+  environment: string;
+  /** Publish a background job */
+  publishJob: (type: string, payload: unknown) => Promise<string>;
+  /** Extensible — apps add whatever their plugins need */
+  [key: string]: unknown;
+}
+
+/**
+ * What a plugin contributes to the application.
+ */
+export interface PluginContribution {
+  /** Routes this plugin handles (matched in plugin array order) */
+  routes?: Route[];
+  /** Named handlers for cross-plugin reference (e.g., SSR as fallback) */
+  handlers?: Record<string, Handler>;
+  /** CLI actions this plugin handles (invoked via Lambda direct invoke) */
+  actions?: Record<string, ActionHandler>;
+  /** Log sink — at most one plugin should provide this */
+  logSink?: LogSink;
+}
+
+/**
+ * An action handler receives the payload and the shared context.
+ * No module-level globals needed — context is injected.
+ */
+export type ActionHandler = (
+  payload: unknown,
+  ctx: PluginContext
+) => Promise<unknown>;
+
+/**
+ * A plugin is a factory function.
+ * It receives the shared context and returns its contributions.
+ * Called lazily during init — dynamic imports go inside the factory body.
+ */
+export type Plugin = (ctx: PluginContext) => Promise<PluginContribution>;
+
+// --- Plugin Lambda Handler Options ---
+
+export interface PluginLambdaHandlerOptions {
+  /**
+   * Creates the shared context that all plugins receive.
+   * Called once on first request (lazy init for cold starts).
+   */
+  context: () => Promise<PluginContext>;
+  /**
+   * Plugins to compose. Order matters for route priority —
+   * earlier plugins' routes match first.
+   */
+  plugins: Plugin[];
+  /**
+   * App-level routes that don't belong to any plugin.
+   * Evaluated after plugin routes.
+   */
+  routes?: (ctx: PluginContext) => Route[];
+  /**
+   * Fallback handler when no route matches (e.g., SSR).
+   * Can be async if the handler requires initialization.
+   */
+  fallback?: (ctx: PluginContext) => Handler | Promise<Handler>;
+  /**
+   * App-level actions merged with plugin-contributed actions.
+   * App actions take precedence over plugin actions on name collision.
+   */
+  actions?: Record<string, ActionHandler>;
+  /** Override default Cache-Control headers */
+  cache?: ServerCacheConfig;
+}
+
+// --- Plugin Lambda Handler Implementation ---
+
+export function createPluginLambdaHandler(
+  options: PluginLambdaHandlerOptions
+): (event: APIGatewayProxyEventV2 | Record<string, unknown>) => Promise<APIGatewayProxyStructuredResultV2 | unknown> {
+  let cached: {
+    ctx: PluginContext;
+    router: (path: string, method: string) => Handler;
+    actions: Record<string, ActionHandler>;
+    logSink?: LogSink;
+  } | null = null;
+
+  async function ensureInitialized() {
+    if (cached) return cached;
+
+    const ctx = await options.context();
+
+    // Initialize all plugins (sequential to allow import ordering)
+    const contributions: PluginContribution[] = [];
+    for (const plugin of options.plugins) {
+      contributions.push(await plugin(ctx));
+    }
+
+    // Collect routes (plugin order = priority)
+    const pluginRoutes = contributions.flatMap(c => c.routes ?? []);
+    const appRoutes = options.routes?.(ctx) ?? [];
+    const allRoutes = [...pluginRoutes, ...appRoutes];
+
+    // Collect actions (app-level takes precedence on collision)
+    const pluginActions: Record<string, ActionHandler> = {};
+    for (const contribution of contributions) {
+      if (contribution.actions) {
+        Object.assign(pluginActions, contribution.actions);
+      }
+    }
+    const allActions = { ...pluginActions, ...(options.actions ?? {}) };
+
+    // Collect log sink (first one wins)
+    const logSink = contributions.find(c => c.logSink)?.logSink;
+
+    // Build router
+    const fallback = await options.fallback?.(ctx);
+    const router = createRouter(allRoutes, fallback);
+
+    cached = { ctx, router, actions: allActions, logSink };
+    log('info', 'Plugin handlers initialized', { plugins: options.plugins.length });
+    return cached;
+  }
+
+  return async (
+    event: APIGatewayProxyEventV2 | Record<string, unknown>
+  ): Promise<APIGatewayProxyStructuredResultV2 | unknown> => {
+    // Direct CLI invoke via Lambda Invoke — IAM is the auth layer.
+    if ('_action' in event && typeof event._action === 'string') {
+      const { ctx, actions } = await ensureInitialized();
+      const actionName = event._action;
+      const actionHandler = actions[actionName];
+      if (!actionHandler) {
+        return { error: `Unknown action: ${actionName}` };
+      }
+      log('info', 'CLI action invoked', { action: actionName });
+      try {
+        return await actionHandler(event._payload, ctx);
+      } catch (error) {
+        log('error', 'CLI action error', { action: actionName, error: String(error) });
+        return { error: String(error) };
+      }
+    }
+
+    // HTTP event — Function URL or API Gateway
+    const httpEvent = event as APIGatewayProxyEventV2;
+    const requestId =
+      httpEvent.headers?.['x-amzn-trace-id'] ||
+      httpEvent.headers?.['x-request-id'] ||
+      crypto.randomUUID();
+
+    try {
+      const { router, logSink } = await ensureInitialized();
+      const request = eventToRequest(httpEvent);
+      const path = httpEvent.rawPath;
+      const method = httpEvent.requestContext.http.method;
+      const handlerFn = router(path, method);
+      const response = await handlerFn(request);
+      const result = await responseToResult(response);
+
+      // Propagate request ID
+      result.headers = { ...result.headers, 'x-request-id': requestId };
+
+      // Set Cache-Control if not already set by the handler
+      if (!result.headers['cache-control']) {
+        if (method === 'GET' || method === 'HEAD') {
+          const isAuthenticated = !!httpEvent.headers?.authorization;
+          result.headers['cache-control'] = isAuthenticated
+            ? (options.cache?.private ?? 'private, no-store')
+            : (options.cache?.public ?? 'public, max-age=60, s-maxage=2592000, stale-while-revalidate=5');
+        } else {
+          result.headers['cache-control'] = options.cache?.mutation ?? 'no-store';
+        }
+      }
+
+      // Response size guard — Lambda Function URLs have a 6MB limit
+      if (result.body && result.body.length > 5 * 1024 * 1024) {
+        return {
+          statusCode: 413,
+          headers: {
+            'Content-Type': 'application/json',
+            'cache-control': 'no-store',
+            'x-request-id': requestId,
+          },
+          body: JSON.stringify({ error: 'Response too large' }),
+        };
+      }
+
+      log('info', 'Request completed', {
+        requestId,
+        path,
+        method,
+        status: result.statusCode,
+      });
+
+      // Write to log sink (non-blocking)
+      if (logSink) {
+        logSink.ingest([{
+          id: requestId,
+          timestamp: Date.now(),
+          level: (result.statusCode ?? 200) >= 500 ? 'error' : 'info',
+          message: `${method} ${path} ${result.statusCode ?? 200}`,
+          source: 'lambda',
+          traceId: requestId,
+          data: { path, method, status: result.statusCode ?? 200, platform: 'server' },
+        }]).catch(() => {});
+      }
+
+      return result;
+    } catch (error) {
+      log('error', 'Lambda handler error', {
+        requestId,
+        error: String(error),
+      });
+      return {
+        statusCode: 500,
+        headers: {
+          'Content-Type': 'application/json',
+          'cache-control': 'no-store',
+          'x-request-id': requestId,
+        },
+        body: JSON.stringify({
+          error: 'Internal Server Error',
+          ...(process.env.ENVIRONMENT === 'dev'
+            ? { details: String(error) }
+            : {}),
+        }),
+      };
+    }
+  };
+}
+
+// --- SSR Fallback Plugin ---
+
+import type { PostProcessResult, WebHandlerOptions } from './ssr';
+
+export interface SsrPluginOptions {
+  /** App-specific HTML post-processing (e.g., JSON-LD injection, meta status codes) */
+  postProcessHtml?: (html: string, request: Request) => PostProcessResult | Promise<PostProcessResult>;
+  /** Channel name for bundle resolution (default: from ENVIRONMENT env var) */
+  channel?: string;
+  /** Query params to strip before SSR (default: ['_v']) */
+  stripQueryParams?: string[];
+  /** Inject __EXPO_ROUTER_HYDRATE__ flag (default: true) */
+  injectHydrateFlag?: boolean;
+}
+
+interface SsrContext extends PluginContext {
+  updatesStorage: any;
+}
+
+/**
+ * Creates an SSR fallback handler from plugin context.
+ * Resolves the web handler from S3/storage, extracts auth from cookies,
+ * and runs each request with auth context for SSR loaders.
+ *
+ * Usage:
+ *   fallback: ssrPlugin(),
+ *   fallback: ssrPlugin({ postProcessHtml: injectJsonLd }),
+ */
+export function ssrPlugin(options: SsrPluginOptions = {}): (ctx: PluginContext) => Promise<Handler> {
+  return async (ctx: PluginContext): Promise<Handler> => {
+    const { getWebHandler } = await import('./ssr');
+
+    // Auth helpers are optional — SSR works without auth (just no user context)
+    let getTokenFromCookies: ((cookieHeader: string | null) => string | null) | null = null;
+    let runWithAuthContext: (<T>(user: any, fn: () => T | Promise<T>) => T | Promise<T>) | null = null;
+    try {
+      const cookies = await import('@everystack/auth/cookies');
+      const context = await import('@everystack/auth/context');
+      getTokenFromCookies = cookies.getTokenFromCookies;
+      runWithAuthContext = context.runWithAuthContext;
+    } catch {
+      // @everystack/auth not installed — SSR works without auth context
+    }
+
+    const ssrOptions: Partial<WebHandlerOptions> = {};
+    if (options.postProcessHtml) ssrOptions.postProcessHtml = options.postProcessHtml;
+    if (options.channel) ssrOptions.channel = options.channel;
+    if (options.stripQueryParams) ssrOptions.stripQueryParams = options.stripQueryParams;
+    if (options.injectHydrateFlag !== undefined) ssrOptions.injectHydrateFlag = options.injectHydrateFlag;
+
+    return async (request: Request): Promise<Response> => {
+      const webHandler = await getWebHandler(
+        (ctx as SsrContext).updatesStorage,
+        { db: ctx.db, ...ssrOptions },
+      );
+      if (!webHandler) return new Response('Not Found', { status: 404 });
+
+      // Extract auth context from cookie for SSR loaders
+      let user: Record<string, unknown> | null = null;
+      if (getTokenFromCookies && runWithAuthContext) {
+        const cookieHeader = request.headers.get('cookie');
+        if (cookieHeader) {
+          const token = getTokenFromCookies(cookieHeader);
+          if (token) {
+            const claims = await ctx.verifyToken(token);
+            if (claims && typeof claims.sub === 'string') {
+              user = claims;
+            }
+          }
+        }
+        return runWithAuthContext(user, () => webHandler(request));
+      }
+
+      return webHandler(request);
+    };
+  };
+}
+
+// --- Database Actions Plugin ---
+
+export interface DbPluginOptions {
+  /** Absolute path to drizzle migrations folder */
+  migrationsFolder: string;
+  /** App-provided seed function — action only registered if provided */
+  seed?: (db: any, schema: any) => Promise<any>;
+  /** PostgreSQL schemas to drop during db:reset (default: ['public', 'drizzle']) */
+  schemas?: string[];
+  /** Connection info callback for db:psql (falls back to SST Resource.Database) */
+  connectionInfo?: () => Promise<Record<string, string>>;
+  /** Enable console action (default: true) */
+  allowConsole?: boolean;
+  /** Read replica URL for db:query (default: process.env.READ_DATABASE_URL) */
+  readDatabaseUrl?: string;
+}
+
+/**
+ * Database administration actions as a plugin.
+ * Contributes: migrate, seed, db:reset, db:psql, db:query, console.
+ *
+ * Usage:
+ *   dbPlugin({ migrationsFolder: join(__dirname, '..', 'drizzle'), seed: runSeed })
+ */
+export function dbPlugin(options: DbPluginOptions): Plugin {
+  return async (ctx: PluginContext): Promise<PluginContribution> => {
+    const actions: Record<string, ActionHandler> = {};
+
+    // --- migrate ---
+    actions.migrate = async (_payload, ctx) => {
+      const { runMigrations } = await import('./migrate');
+      return await runMigrations(ctx.db, options.migrationsFolder);
+    };
+
+    // --- seed (only when app provides a seed function) ---
+    if (options.seed) {
+      const seedFn = options.seed;
+      actions.seed = async (_payload, ctx) => {
+        if (ctx.environment !== 'dev') {
+          return { error: 'Seed is only available in dev environment' };
+        }
+        return await seedFn(ctx.db, ctx.schema);
+      };
+    }
+
+    // --- db:reset ---
+    actions['db:reset'] = async (_payload, ctx) => {
+      if (ctx.environment !== 'dev') {
+        return { error: 'db:reset is only available in dev environment' };
+      }
+      const { sql } = await import('drizzle-orm');
+      const schemas = options.schemas ?? ['public', 'drizzle'];
+      const dropStatements = schemas
+        .map(s => `DROP SCHEMA IF EXISTS ${s} CASCADE;`)
+        .join('\n    ');
+      await ctx.db.execute(sql.raw(`
+    ${dropStatements}
+    CREATE SCHEMA public;
+    GRANT ALL ON SCHEMA public TO postgres;
+    GRANT ALL ON SCHEMA public TO public;
+  `));
+      const { runMigrations } = await import('./migrate');
+      const result = await runMigrations(ctx.db, options.migrationsFolder);
+      return { reset: true, ...result };
+    };
+
+    // --- db:psql ---
+    actions['db:psql'] = async () => {
+      if (options.connectionInfo) {
+        return await options.connectionInfo();
+      }
+      try {
+        const { Resource } = await import('sst');
+        return {
+          host: (Resource as any).Database.host,
+          port: (Resource as any).Database.port,
+          database: (Resource as any).Database.database,
+          username: (Resource as any).Database.username,
+          password: (Resource as any).Database.password,
+        };
+      } catch {
+        return { error: 'No connectionInfo callback provided and SST Resource.Database not available' };
+      }
+    };
+
+    // --- db:query ---
+    actions['db:query'] = async (payload, ctx) => {
+      const { sql: querySql } = payload as { sql: string };
+      if (!querySql) {
+        return { error: 'SQL query is required' };
+      }
+      const writePatterns = [
+        /^INSERT\s/i, /^UPDATE\s/i, /^DELETE\s/i, /^DROP\s/i,
+        /^CREATE\s/i, /^ALTER\s/i, /^TRUNCATE\s/i, /^GRANT\s/i, /^REVOKE\s/i,
+      ];
+      if (writePatterns.some(p => p.test(querySql.trim()))) {
+        return {
+          error: 'Write operations are not allowed via db:query. Use db:migrate, seed, or console for write operations.',
+        };
+      }
+      try {
+        const { sql } = await import('drizzle-orm');
+        let queryDb = ctx.db;
+        const readUrl = options.readDatabaseUrl ?? process.env.READ_DATABASE_URL;
+        if (readUrl && readUrl !== process.env.DATABASE_URL) {
+          const { drizzle } = await import('drizzle-orm/postgres-js');
+          const postgres = (await import('postgres')).default;
+          queryDb = drizzle(postgres(readUrl, { max: 1, idle_timeout: 20, connect_timeout: 10 }));
+        }
+        const result: any = await queryDb.execute(sql.raw(querySql));
+        const rows = Array.isArray(result) ? result : result.rows || [];
+        return { rows };
+      } catch (err: any) {
+        return { error: err.message || String(err) };
+      }
+    };
+
+    // --- console ---
+    if (options.allowConsole !== false) {
+      actions.console = async (payload, ctx) => {
+        const { expression } = payload as { expression: string };
+        if (!expression) return { error: 'No expression provided' };
+        try {
+          const { eq, and, or, gt, lt, gte, lte, ne, count, sum, avg, sql, desc, asc } =
+            await import('drizzle-orm');
+          const evalContext: Record<string, unknown> = {
+            db: ctx.db, schema: ctx.schema,
+            eq, and, or, gt, lt, gte, lte, ne, count, sum, avg, sql, desc, asc,
+          };
+          const AsyncFunction = Object.getPrototypeOf(async function(){}).constructor;
+          const fn = new AsyncFunction(
+            ...Object.keys(evalContext),
+            `return (${expression})`,
+          );
+          const result = await fn(...Object.values(evalContext));
+          return { result };
+        } catch (err: any) {
+          return { error: err.message || String(err) };
+        }
+      };
+    }
+
+    return { actions };
+  };
+}
+
+// --- Plugin Handler for Non-Lambda Runtimes (Expo Router, Bun, Deno) ---
+
+/**
+ * Creates a Web Standard handler from plugins — no Lambda, no event adaptation.
+ * For use with Expo Router API routes, Bun.serve, Deno.serve, etc.
+ */
+export function createPluginHandler(options: {
+  context: () => Promise<PluginContext>;
+  plugins: Plugin[];
+  routes?: (ctx: PluginContext) => Route[];
+  fallback?: (ctx: PluginContext) => Handler | Promise<Handler>;
+}): Handler {
+  let cached: { router: (path: string, method: string) => Handler } | null = null;
+
+  return async (request: Request): Promise<Response> => {
+    if (!cached) {
+      const ctx = await options.context();
+      const contributions: PluginContribution[] = [];
+      for (const plugin of options.plugins) {
+        contributions.push(await plugin(ctx));
+      }
+      const pluginRoutes = contributions.flatMap(c => c.routes ?? []);
+      const appRoutes = options.routes?.(ctx) ?? [];
+      const allRoutes = [...pluginRoutes, ...appRoutes];
+      const fallback = await options.fallback?.(ctx);
+      cached = { router: createRouter(allRoutes, fallback) };
+    }
+
+    const url = new URL(request.url);
+    const handler = cached.router(url.pathname, request.method);
+    return handler(request);
+  };
+}

package/src/ssr.ts

@@ -79,13 +79,13 @@ export interface WebHandlerOptions {
     PostProcessResult | Promise<PostProcessResult>;
 }
 
-const DEFAULT_STRIP_PARAMS = ['_v'];
+const DEFAULT_STRIP_PARAMS = ['_v', '_a'];
 const HYDRATE_SCRIPT = '<script>globalThis.__EXPO_ROUTER_HYDRATE__=true;</script>\n';
 
 /**
  * Wraps an SSR request handler with framework-level fixes:
  *
- *   1. Strips CFF query params (_v) so expo-router loader data keys
+ *   1. Strips CFF query params (_v, _a) so expo-router loader data keys
  *      match the client-side route path (which has no CFF params).
  *   2. Injects `__EXPO_ROUTER_HYDRATE__=true` before `</head>` so React
  *      Native Web uses `hydrateRoot()` instead of `createRoot()`.
@@ -278,7 +278,7 @@ export async function getWebHandler(
   options?: WebHandlerOptions,
 ): Promise<((request: Request) => Promise<Response>) | null> {
   const now = Date.now();
-  const channel = options?.channel || 'production';
+  const channel = options?.channel || process.env.ENVIRONMENT || 'production';
   const buildDir = `${BUILD_DIR_BASE}/${channel}`;
 
   const cached = cachedHandlers.get(channel);

package/src/worker.ts

@@ -7,6 +7,26 @@
 
 import { log } from './index.js';
 
+/** Job shape — mirrors @everystack/jobs Job interface (type-compatible, no circular dep). */
+export interface WorkerJob<T = unknown> {
+  id: string;
+  type: string;
+  payload: T;
+  status: 'pending' | 'active' | 'completed' | 'failed' | 'dead';
+  attempts: number;
+  maxAttempts: number;
+  priority: number;
+  runAt: Date;
+  lockedAt: Date | null;
+  lockedBy: string | null;
+  completedAt: Date | null;
+  failedAt: Date | null;
+  error: string | null;
+  createdAt: Date;
+}
+
+export type JobHandler<T = unknown> = (payload: T, job: WorkerJob<T>) => Promise<void>;
+
 export interface SQSEvent {
   Records: Array<{
     messageId: string;
@@ -20,7 +40,30 @@ export interface SQSBatchResponse {
   batchItemFailures: Array<{ itemIdentifier: string }>;
 }
 
-export type JobHandler = (payload: any, job: { id: string; type: string }) => Promise<void>;
+/**
+ * Build a Job object from SQS message fields.
+ * Fills required Job properties with sensible defaults — the handler
+ * receives a complete Job even without a database.
+ */
+function jobFromSqsMessage(jobId: string, type: string, payload: unknown): WorkerJob {
+  const now = new Date();
+  return {
+    id: jobId,
+    type,
+    payload,
+    status: 'active',
+    attempts: 1,
+    maxAttempts: 3,
+    priority: 0,
+    runAt: now,
+    lockedAt: now,
+    lockedBy: null,
+    completedAt: null,
+    failedAt: null,
+    error: null,
+    createdAt: now,
+  };
+}
 
 export function createWorkerHandler(
   init: () => Promise<Record<string, JobHandler>>
@@ -50,7 +93,8 @@ export function createWorkerHandler(
           continue;
         }
 
-        await handlerFn(payload, { id: jobId, type });
+        const job = jobFromSqsMessage(jobId, type, payload);
+        await handlerFn(payload, job);
         log('info', 'Job completed', { type, jobId });
       } catch (error) {
         log('error', 'Job failed', { messageId: record.messageId, error: String(error) });