@blamejs/core 0.4.18 → 0.4.19

package/CHANGELOG.md

@@ -8,6 +8,7 @@ upgrading across more than a few patches at a time.
 
 ## v0.4.x
 
+- **0.4.18** (2026-04-30) — cookieJar forensic-test strengthening (real crypto, replay, nonce)
 - **0.4.17** (2026-04-30) — b.httpClient.cookieJar (encrypted) + wiki catch-up sweep
 - **0.4.16** (2026-04-30) — b.httpClient: interceptors + progress events
 - **0.4.15** (2026-04-30) — b.httpClient: redirect-following + outbound multipart

package/lib/router.js

@@ -30,6 +30,114 @@ var { boot } = require("./log");
 
 var log = boot("router");
 
+// ---- Schema-spec helpers (route-level body/query/params validation) ----
+
+var ALLOWED_SPEC_KEYS = [
+  "body", "query", "params", "response",
+  "bodyJsonSchema", "queryJsonSchema", "paramsJsonSchema", "responseJsonSchema",
+  "description", "summary", "tags", "validateResponse",
+];
+
+function _validateRouteSpec(spec, method, pattern) {
+  var keys = Object.keys(spec);
+  for (var i = 0; i < keys.length; i++) {
+    if (ALLOWED_SPEC_KEYS.indexOf(keys[i]) === -1) {
+      throw new Error("router." + method.toLowerCase() + "(" + pattern +
+        "): unknown spec key '" + keys[i] + "'. Allowed: " +
+        ALLOWED_SPEC_KEYS.slice().sort().join(", "));
+    }
+  }
+  function _checkSchema(name) {
+    var s = spec[name];
+    if (s === undefined) return;
+    if (!s || typeof s !== "object" || typeof s.safeParse !== "function") {
+      throw new Error("router." + method.toLowerCase() + "(" + pattern +
+        "): spec." + name + " must be a b.safeSchema-shaped schema (with safeParse)");
+    }
+  }
+  _checkSchema("body");
+  _checkSchema("query");
+  _checkSchema("params");
+  _checkSchema("response");
+  if (spec.tags !== undefined) {
+    if (!Array.isArray(spec.tags) || !spec.tags.every(function (t) { return typeof t === "string"; })) {
+      throw new Error("router." + method.toLowerCase() + "(" + pattern +
+        "): spec.tags must be an array of strings");
+    }
+  }
+}
+
+function _writeValidationError(res, where, errors) {
+  if (res.writableEnded || res.headersSent) return;
+  var body = JSON.stringify({
+    error: "validation",
+    where: where,
+    issues: errors,
+  });
+  res.writeHead(400, {
+    "Content-Type":   "application/json; charset=utf-8",
+    "Content-Length": Buffer.byteLength(body),
+  });
+  res.end(body);
+}
+
+function _makeSchemaValidator(spec) {
+  // 3-arg signature → router treats as middleware, chains via next().
+  return function schemaValidator(req, res, next) {
+    if (spec.params && req.params !== undefined) {
+      var pp = spec.params.safeParse(req.params);
+      if (!pp.ok) return _writeValidationError(res, "params", pp.errors);
+      req.params = pp.value;
+    }
+    if (spec.query && req.query !== undefined) {
+      var qq = spec.query.safeParse(req.query);
+      if (!qq.ok) return _writeValidationError(res, "query", qq.errors);
+      req.query = qq.value;
+    }
+    if (spec.body && req.body !== undefined) {
+      var bb = spec.body.safeParse(req.body);
+      if (!bb.ok) return _writeValidationError(res, "body", bb.errors);
+      req.body = bb.value;
+    }
+    next();
+  };
+}
+
+function _makeResponseValidator(spec) {
+  // Wraps res.json (and res.end when called with a JSON-shaped buffer)
+  // to validate the response body against spec.response. Mode:
+  //   - BLAMEJS_VALIDATE_RESPONSES=throw (or per-route validateResponse: "throw")
+  //     → throw a SafeSchemaError-shaped error; route handler's caller sees a 500.
+  //   - BLAMEJS_VALIDATE_RESPONSES=warn (or per-route validateResponse: "warn")
+  //     → log a warning; ship the response as-is (prod-safe).
+  var perRoute = spec.validateResponse;
+  var globalMode = process.env.BLAMEJS_VALIDATE_RESPONSES;
+  var mode = (perRoute === "throw" || perRoute === "warn") ? perRoute :
+             (globalMode === "throw" || globalMode === "warn") ? globalMode : null;
+  if (!mode) return function passthrough(_req, _res, next) { next(); };
+
+  return function responseValidator(req, res, next) {
+    var origJson = typeof res.json === "function" ? res.json.bind(res) : null;
+    if (origJson) {
+      res.json = function (value) {
+        var rr = spec.response.safeParse(value);
+        if (!rr.ok) {
+          if (mode === "throw") {
+            throw new Error("router response-validation failed for " +
+              (req.method + " " + req.routePattern) + ": " +
+              JSON.stringify(rr.errors));
+          }
+          // warn mode
+          log.warn("response-validation drift on " + req.method + " " + req.routePattern +
+                   ": " + JSON.stringify(rr.errors).slice(0, 500));
+        }
+        return origJson(value);
+      };
+    }
+    next();
+  };
+}
+
 function compilePattern(pattern) {
   var keys = [];
   var regexStr = pattern
@@ -128,24 +236,154 @@ class Router {
     this.middleware.push(fn);
   }
 
-  get(pattern, ...handlers) {
-    this.routes.push({ method: "GET", ...compilePattern(pattern), handlers });
+  // Internal: split a route registration's args into { spec, handlers }.
+  // The first non-pattern arg is the schema spec when it's a plain object
+  // (not a function); subsequent args are handler middlewares. Operators
+  // who never pass a spec keep the existing two-arg shape working.
+  _splitArgs(args) {
+    if (args.length > 0 && args[0] && typeof args[0] === "object" &&
+        !Array.isArray(args[0]) && typeof args[0] !== "function") {
+      return { spec: args[0], handlers: args.slice(1) };
+    }
+    return { spec: null, handlers: args };
+  }
+
+  _registerRoute(method, pattern, args) {
+    var split = this._splitArgs(args);
+    if (split.spec) _validateRouteSpec(split.spec, method, pattern);
+    var handlers = split.handlers;
+    if (split.spec) {
+      // Pre-handler validates body / query / params. Runs after the
+      // global middleware chain (bodyParser populates req.body before
+      // route dispatch) but before any route-specific handler.
+      handlers = [_makeSchemaValidator(split.spec)].concat(handlers);
+      // Response validation (dev/opt-in via env or per-route opt).
+      if (split.spec.response &&
+          (process.env.BLAMEJS_VALIDATE_RESPONSES === "throw" ||
+           process.env.BLAMEJS_VALIDATE_RESPONSES === "warn" ||
+           split.spec.validateResponse)) {
+        handlers = [_makeResponseValidator(split.spec)].concat(handlers);
+      }
+    }
+    this.routes.push(Object.assign(
+      { method: method, handlers: handlers, spec: split.spec || null },
+      compilePattern(pattern)
+    ));
+  }
+
+  get(pattern, ...args) {
+    this._registerRoute("GET", pattern, args);
+  }
+
+  post(pattern, ...args) {
+    this._registerRoute("POST", pattern, args);
+  }
+
+  put(pattern, ...args) {
+    this._registerRoute("PUT", pattern, args);
   }
 
-  post(pattern, ...handlers) {
-    this.routes.push({ method: "POST", ...compilePattern(pattern), handlers });
+  patch(pattern, ...args) {
+    this._registerRoute("PATCH", pattern, args);
   }
 
-  put(pattern, ...handlers) {
-    this.routes.push({ method: "PUT", ...compilePattern(pattern), handlers });
+  delete(pattern, ...args) {
+    this._registerRoute("DELETE", pattern, args);
   }
 
-  patch(pattern, ...handlers) {
-    this.routes.push({ method: "PATCH", ...compilePattern(pattern), handlers });
+  // Operator-facing introspection — returns a copy of the route table
+  // with each entry's method, pattern, description, and (when provided)
+  // operator-supplied jsonSchema bodies for OpenAPI publication.
+  inspectRoutes() {
+    return this.routes
+      .filter(function (r) { return typeof r.method === "string"; })
+      .map(function (r) {
+        return {
+          method:      r.method,
+          pattern:     r.pattern,
+          description: r.spec ? r.spec.description || null : null,
+          spec:        r.spec ? {
+            hasBodySchema:   !!r.spec.body,
+            hasQuerySchema:  !!r.spec.query,
+            hasParamsSchema: !!r.spec.params,
+            hasResponseSchema: !!r.spec.response,
+            bodyJsonSchema:     r.spec.bodyJsonSchema     || null,
+            queryJsonSchema:    r.spec.queryJsonSchema    || null,
+            paramsJsonSchema:   r.spec.paramsJsonSchema   || null,
+            responseJsonSchema: r.spec.responseJsonSchema || null,
+            tags:        Array.isArray(r.spec.tags) ? r.spec.tags.slice() : [],
+            summary:     r.spec.summary || null,
+          } : null,
+        };
+      });
   }
 
-  delete(pattern, ...handlers) {
-    this.routes.push({ method: "DELETE", ...compilePattern(pattern), handlers });
+  // openapi(opts?) → minimal Swagger 3.0 document covering every
+  // schema-spec'd route. Body / query / params show up as parameter
+  // entries when the operator supplies bodyJsonSchema / etc. (a
+  // safeSchema → JSON Schema converter is its own primitive — operators
+  // who want full schema bodies in the OpenAPI doc supply the JSON
+  // Schema alongside the safeSchema today).
+  openapi(opts) {
+    opts = opts || {};
+    var info = opts.info || { title: "blamejs app", version: "0.0.0" };
+    var paths = {};
+    var routes = this.inspectRoutes();
+    for (var i = 0; i < routes.length; i++) {
+      var r = routes[i];
+      var openapiPath = r.pattern.replace(/:([a-zA-Z0-9_]+)/g, "{$1}");
+      if (!paths[openapiPath]) paths[openapiPath] = {};
+      var op = {
+        summary:     r.spec ? r.spec.summary || r.description || (r.method + " " + r.pattern) :
+                              (r.method + " " + r.pattern),
+        description: r.description || null,
+      };
+      if (r.spec) {
+        op.tags = r.spec.tags;
+        var params = [];
+        // Path params from pattern
+        var pathParams = (r.pattern.match(/:[a-zA-Z0-9_]+/g) || [])
+          .map(function (s) { return s.slice(1); });
+        for (var pp = 0; pp < pathParams.length; pp++) {
+          params.push({ name: pathParams[pp], in: "path", required: true,
+                        schema: { type: "string" } });
+        }
+        if (r.spec.queryJsonSchema && r.spec.queryJsonSchema.properties) {
+          var qprops = r.spec.queryJsonSchema.properties;
+          var qreq   = r.spec.queryJsonSchema.required || [];
+          var qkeys  = Object.keys(qprops);
+          for (var qi = 0; qi < qkeys.length; qi++) {
+            params.push({ name: qkeys[qi], in: "query",
+                          required: qreq.indexOf(qkeys[qi]) !== -1,
+                          schema: qprops[qkeys[qi]] });
+          }
+        }
+        if (params.length > 0) op.parameters = params;
+        if (r.spec.bodyJsonSchema) {
+          op.requestBody = {
+            required: true,
+            content: { "application/json": { schema: r.spec.bodyJsonSchema } },
+          };
+        } else if (r.spec.hasBodySchema) {
+          // Operator validates via safeSchema but didn't supply JSON Schema.
+          op["x-blamejs-body-validation"] = "safe-schema (json schema not provided)";
+        }
+        if (r.spec.responseJsonSchema) {
+          op.responses = {
+            "200": {
+              description: "OK",
+              content: { "application/json": { schema: r.spec.responseJsonSchema } },
+            },
+          };
+        }
+      }
+      paths[openapiPath][r.method.toLowerCase()] = op;
+    }
+    return {
+      openapi: "3.0.3",
+      info:    info,
+      paths:   paths,
+    };
   }
 
   // ---- WebSocket route registration ----

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.4.18",
+  "version": "0.4.19",
   "description": "The Node framework that owns its stack.",
   "license": "Apache-2.0",
   "author": "blamejs contributors",