@emeryld/rrroutes-server 2.4.8 → 2.5.0

package/README.md

@@ -68,8 +68,8 @@ const server = createRRRoute(app, {
     user: await loadUser(req),
     routesLogger: console,
   }), // ctx lives on res.locals[CTX_SYMBOL]
-  globalMiddleware: {
-    before: [
+  middleware: {
+    postCtx: [
       ({ ctx, next }) => {
         if (!ctx.user) throw new Error('unauthorized')
         next()
@@ -169,7 +169,7 @@ const server = createRRRoute(app, {
 
 ### Middleware order and ctx usage
 
-Order: `resolve` → `ctx` → `global.before` → `route.before` → handler.
+Order: `sanitizer` → `preCtx` → `resolve` → `ctx` → `postCtx` → `route.before` → handler.
 
 ```ts
 import { getCtx, CtxRequestHandler } from '@emeryld/rrroutes-server'
@@ -181,7 +181,7 @@ const audit: CtxRequestHandler<Ctx> = ({ ctx, req, next }) => {
 
 const server = createRRRoute(app, {
   buildCtx: (req, res) => ({ user: res.locals.user, routesLogger: console }),
-  globalMiddleware: { before: [audit] },
+  middleware: { postCtx: [audit] },
 })
 
 const routeBefore = ({ params, query, body, ctx, next }) => {
@@ -199,7 +199,38 @@ app.use((req, res, next) => {
 
 - `CtxRequestHandler` receives `{ req, res, next, ctx }` with your typed ctx.
 - `route.before` handlers now receive the same parsed `params`, `query`, and `body` payload as the handler, alongside `req`, `res`, and `ctx`.
-- Need post-response hooks? Register a middleware that wires `res.on('finish', handler)` inside `route.before`/`global.before` instead of relying on a dedicated "after" stage.
+- Need post-response hooks? Register a middleware that wires `res.on('finish', handler)` inside `route.before`/`middleware.postCtx` instead of relying on a dedicated "after" stage.
+
+### Request sanitization
+
+Use `middleware.sanitizer` when you want to sanitize raw request data before RRRoutes parses params/query/body.
+
+```ts
+const server = createRRRoute(app, {
+  buildCtx,
+  middleware: {
+    sanitizer: {
+      trimStrings: true,
+      customSanitizer: (value, context) => {
+        if (context.target === 'query' && typeof value === 'string') {
+          return value.toLowerCase()
+        }
+        return value
+      },
+    },
+  },
+})
+```
+
+By default, the sanitizer:
+
+- strips null bytes from strings
+- removes prototype-pollution keys (`__proto__`, `prototype`, `constructor`)
+- keeps whitespace unless `trimStrings: true` is set
+
+`blockedKeys` exists to prevent prototype-pollution payloads from surviving into downstream object merges.
+
+For full sanitizer docs/options, see `./SANITIZER.md`.
 
 ### Upload parsing
 
@@ -272,7 +303,7 @@ Context logger passthrough: if `buildCtx` provides `routesLogger`, handler debug
 
 - **Combine registries:** build leaves per domain, spread before `finalize([...usersLeaves, ...projectsLeaves])`, then register once.
 - **Fail fast on missing controllers:** use `bindAll(...)` for compile-time coverage or call `warnMissingControllers(...)` during startup to surface missing routes.
-- **Operator-specific middleware:** attach `route.before` per controller (e.g., role checks) and keep `global.before` minimal (auth/session parsing).
+- **Operator-specific middleware:** attach `route.before` per controller (e.g., role checks) and keep `middleware.postCtx` minimal (auth/session parsing).
 
 ## Socket server (typed events, heartbeat, rooms)
 

package/dist/index.cjs

@@ -37,9 +37,11 @@ __export(index_exports, {
   contractKeyOf: () => import_rrroutes_contract2.keyOf,
   createConnectionLoggingMiddleware: () => createConnectionLoggingMiddleware,
   createRRRoute: () => createRRRoute,
+  createRequestSanitizationMiddleware: () => createRequestSanitizationMiddleware,
   createSocketConnections: () => createSocketConnections,
   defineControllers: () => defineControllers,
   getCtx: () => getCtx,
+  requestSanitizationMiddleware: () => requestSanitizationMiddleware,
   warnMissingControllers: () => warnMissingControllers
 });
 module.exports = __toCommonJS(index_exports);
@@ -48,6 +50,140 @@ var import_rrroutes_contract2 = require("@emeryld/rrroutes-contract");
 // src/routesV3.server.ts
 var import_rrroutes_contract = require("@emeryld/rrroutes-contract");
 var import_multer = __toESM(require("multer"), 1);
+
+// src/routesV3.server.sanitize.ts
+var defaultTargets = ["params", "query", "body"];
+var defaultBlockedKeys = ["__proto__", "prototype", "constructor"];
+var defaultMaxDepth = 20;
+var nullBytePattern = /\u0000/g;
+var isPlainObject = (value) => {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+};
+var normalizeOptions = (options) => {
+  return {
+    targets: new Set(options.targets ?? defaultTargets),
+    trimStrings: options.trimStrings ?? false,
+    stripNullBytes: options.stripNullBytes ?? true,
+    stripPrototypePollutionKeys: options.stripPrototypePollutionKeys ?? true,
+    blockedKeys: new Set(options.blockedKeys ?? defaultBlockedKeys),
+    maxDepth: options.maxDepth ?? defaultMaxDepth,
+    customSanitizer: options.customSanitizer
+  };
+};
+var applyCustomSanitizer = (value, options, context) => {
+  if (!options.customSanitizer) return value;
+  return options.customSanitizer(value, context);
+};
+var sanitizeString = (value, options) => {
+  let next = value;
+  if (options.stripNullBytes && next.includes("\0")) {
+    next = next.replace(nullBytePattern, "");
+  }
+  if (options.trimStrings) {
+    next = next.trim();
+  }
+  return next;
+};
+var sanitizeValue = (value, options, depth, seen, req, target, path) => {
+  const context = {
+    req,
+    target,
+    path,
+    depth
+  };
+  if (depth > options.maxDepth) {
+    return applyCustomSanitizer(value, options, context);
+  }
+  if (typeof value === "string") {
+    const sanitized = sanitizeString(value, options);
+    return applyCustomSanitizer(sanitized, options, context);
+  }
+  if (value && typeof value === "object" && seen.has(value)) {
+    return applyCustomSanitizer(value, options, context);
+  }
+  if (Array.isArray(value)) {
+    seen.add(value);
+    const next = value.map(
+      (entry, index) => sanitizeValue(entry, options, depth + 1, seen, req, target, [
+        ...path,
+        index
+      ])
+    );
+    seen.delete(value);
+    return applyCustomSanitizer(next, options, context);
+  }
+  if (!isPlainObject(value)) {
+    return applyCustomSanitizer(value, options, context);
+  }
+  seen.add(value);
+  const source = value;
+  const objectTarget = Object.getPrototypeOf(source) === null ? /* @__PURE__ */ Object.create(null) : {};
+  for (const [key, entry] of Object.entries(source)) {
+    if (options.stripPrototypePollutionKeys && options.blockedKeys.has(key)) {
+      continue;
+    }
+    ;
+    objectTarget[key] = sanitizeValue(
+      entry,
+      options,
+      depth + 1,
+      seen,
+      req,
+      context.target,
+      [...path, key]
+    );
+  }
+  seen.delete(value);
+  return applyCustomSanitizer(objectTarget, options, context);
+};
+var createRequestSanitizationMiddleware = (options = {}) => {
+  const normalized = normalizeOptions(options);
+  return (req, _res, next) => {
+    try {
+      if (normalized.targets.has("params") && req.params) {
+        req.params = sanitizeValue(
+          req.params,
+          normalized,
+          0,
+          /* @__PURE__ */ new WeakSet(),
+          req,
+          "params",
+          []
+        );
+      }
+      if (normalized.targets.has("query") && req.query) {
+        req.query = sanitizeValue(
+          req.query,
+          normalized,
+          0,
+          /* @__PURE__ */ new WeakSet(),
+          req,
+          "query",
+          []
+        );
+      }
+      if (normalized.targets.has("body") && req.body !== void 0) {
+        req.body = sanitizeValue(
+          req.body,
+          normalized,
+          0,
+          /* @__PURE__ */ new WeakSet(),
+          req,
+          "body",
+          []
+        );
+      }
+      next();
+    } catch (err) {
+      next(err);
+    }
+  };
+};
+var requestSanitizationMiddleware = createRequestSanitizationMiddleware();
+
+// src/routesV3.server.ts
 var serverDebugEventTypes = [
   "register",
   "request",
@@ -81,12 +217,12 @@ function createServerDebugEmitter(option) {
   }
   return disabled;
 }
-var isPlainObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+var isPlainObject2 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 var decodeJsonLikeQueryValue = (value) => {
   if (Array.isArray(value)) {
     return value.map((entry) => decodeJsonLikeQueryValue(entry));
   }
-  if (isPlainObject(value)) {
+  if (isPlainObject2(value)) {
     const next = {};
     for (const [key, child] of Object.entries(value)) {
       next[key] = decodeJsonLikeQueryValue(child);
@@ -110,7 +246,7 @@ var REQUEST_PAYLOAD_SYMBOL = /* @__PURE__ */ Symbol.for(
   "typedLeaves.requestPayload"
 );
 function isMulterFile(value) {
-  if (!isPlainObject(value)) return false;
+  if (!isPlainObject2(value)) return false;
   const candidate = value;
   return typeof candidate.fieldname === "string";
 }
@@ -126,7 +262,7 @@ function collectMulterFiles(req) {
       files.push(value);
       return;
     }
-    if (isPlainObject(value)) {
+    if (isPlainObject2(value)) {
       Object.values(value).forEach(pushValue);
     }
   };
@@ -252,9 +388,12 @@ function createRRRoute(router, config) {
     if (!isVerbose || !details) return event;
     return { ...event, ...details };
   };
-  const globalBeforeMws = [...config.globalMiddleware ?? []].map(
+  const middlewareConfig = config.middleware ?? {};
+  const postCtxMws = [...middlewareConfig.postCtx ?? []].map(
     (mw) => adaptCtxMw(mw)
   );
+  const preCtxMws = [...middlewareConfig.preCtx ?? []];
+  const sanitizerMw = middlewareConfig.sanitizer === void 0 ? void 0 : typeof middlewareConfig.sanitizer === "function" ? middlewareConfig.sanitizer : createRequestSanitizationMiddleware(middlewareConfig.sanitizer);
   const registered = getRegisteredRouteStore(router);
   const getMulterOptions = (fields) => {
     if (!fields || fields.length === 0) return void 0;
@@ -416,9 +555,11 @@ function createRRRoute(router, config) {
       }
     };
     const before = [
+      ...sanitizerMw ? [sanitizerMw] : [],
+      ...preCtxMws,
       resolvePayloadMw,
       ctxMw,
-      ...globalBeforeMws,
+      ...postCtxMws,
       ...routeSpecific
     ];
     const wrapped = async (req, res, next) => {
@@ -1120,7 +1261,10 @@ function createSocketConnections(io, events, opts) {
   });
   io.on("connection", builtInConnectionListener);
   const conn = {
-    on(eventName, handler) {
+    on({
+      eventName,
+      handler
+    }) {
       const socketListeners = /* @__PURE__ */ new WeakMap();
       const connectionListener = (socket) => {
         const wrapped = async (raw) => {
@@ -1229,7 +1373,12 @@ function createSocketConnections(io, events, opts) {
     off(eventName) {
       removeAllForEvent(String(eventName));
     },
-    emitAny(eventName, payload, rooms, metadata) {
+    emitAny({
+      eventName,
+      payload,
+      rooms,
+      metadata
+    }) {
       const targets = toArray2(rooms);
       if (Object.prototype.hasOwnProperty.call(events, eventName)) {
         emitToTargets(
@@ -1426,9 +1575,11 @@ var createConnectionLoggingMiddleware = (options = {}) => {
   contractKeyOf,
   createConnectionLoggingMiddleware,
   createRRRoute,
+  createRequestSanitizationMiddleware,
   createSocketConnections,
   defineControllers,
   getCtx,
+  requestSanitizationMiddleware,
   warnMissingControllers
 });
 //# sourceMappingURL=index.cjs.map