@everystack/server 0.1.0 → 0.2.0

package/package.json

@@ -1,16 +1,16 @@
 {
   "name": "@everystack/server",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Server runtime primitives for Lambda — event adapters, routing, SSR, image processing",
-  "license": "MIT",
+  "license": "AGPL-3.0-only",
   "publishConfig": {
     "access": "public"
   },
   "files": [
     "src",
+    "stubs",
     "README.md"
   ],
-  "type": "module",
   "exports": {
     ".": {
       "types": "./src/index.ts",
@@ -40,20 +40,28 @@
       "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"
     }
   },
   "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": {
@@ -76,20 +84,20 @@
     }
   },
   "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"
+    "@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",
+    "@everystack/cli": "0.2.0",
+    "@everystack/auth": "0.2.0"
   },
   "scripts": {
-    "test": "NODE_OPTIONS='--experimental-vm-modules' jest",
+    "test": "jest",
     "build": "tsc --build",
     "lint": "tsc --noEmit"
   }

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!;
+  }
+}