@blamejs/core 0.7.87 → 0.7.88

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.7.x
 
+- **0.7.88** (2026-05-06) — `b.middleware.webAppManifest` + `b.middleware.assetlinks` — two static-content middlewares for PWA + Trusted Web Activity support. **`b.middleware.webAppManifest({ name, start_url, icons, ... })`** serves the W3C Web App Manifest at `/manifest.webmanifest` (and `/manifest.json` when `alsoAtJsonPath: true`). The framework JSON-serializes once at create() and serves with `Content-Type: application/manifest+json` per the W3C spec + `Cache-Control: public, max-age=86400` + `X-Content-Type-Options: nosniff`. The W3C-spec attribute set is allowlisted (name / short_name / description / start_url / scope / display / display_override / orientation / theme_color / background_color / icons / screenshots / shortcuts / categories / lang / dir / id / prefer_related_applications / related_applications) — typos throw at create. `name`, `start_url`, and at least one icon are required (W3C — installability minimum). HEAD + GET only. **`b.middleware.assetlinks({ statements })`** serves Digital Asset Links at `/.well-known/assetlinks.json` per Google's spec — used by Trusted Web Activity, Android App Links, Smart Lock for Passwords, WebAuthn for Android. Validates each statement carries `relation` (non-empty array) and `target` (object). Same Content-Type / Cache-Control / X-Content-Type-Options posture as the security.txt + manifest emitters.
+
 - **0.7.87** (2026-05-06) — Two route-guard middlewares for API hardening: `b.middleware.requireMethods` + `b.middleware.requireContentType`. **`b.middleware.requireMethods(["GET", "POST"])`** refuses any HTTP method outside the allowlist with `405 Method Not Allowed` + `Allow:` header listing the allowed methods (per RFC 9110 §15.5.6). Defends against unexpected verb routing — many CVE-class bugs trace to a route handler wired for GET that accidentally accepts arbitrary verbs (PROPFIND, OPTIONS, custom). **`b.middleware.requireContentType(["application/json"])`** refuses requests with a body (POST/PUT/PATCH by default) whose `Content-Type` isn't in the allowlist with `415 Unsupported Media Type` + `Accept:` header listing the allowed types (RFC 9110 §15.5.16). Defends against MIME-type confusion — a route that processes JSON shouldn't accept `application/x-www-form-urlencoded` even if the body parses. Both middlewares emit observability events (`middleware.requireMethods.denied` / `middleware.requireContentType.denied`) on every refusal for triage. Operators wanting to enforce content-type on idempotent verbs that DO carry bodies (rare DELETE-with-body shapes) override the default body-method list via `requireContentType(types, { methods })`.
 
 - **0.7.86** (2026-05-06) — `b.middleware.csrfProtect({ requireJsonContentType: true })` — strict-fetch mode for JSON-only API surfaces. State-changing requests (POST/PUT/PATCH/DELETE) without `Content-Type: application/json` are refused before the token check with `CSRF: state-changing requests require Content-Type: application/json.` and audit emission `csrf.denied` with `reason: "non-JSON content-type: ..."`. The browser's form-encoded POST shape is the canonical CSRF vector — a malicious page can `<form action="/transfer" method=POST>` a victim into a state-changing request without a preflight. An `application/json` body forces a CORS preflight (the browser refuses to skip it for non-simple Content-Type values), so an attacker without an operator-allowlisted CORS origin can't reach the route at all. Default `false` — operators with HTML form submissions on the same routes (mixed SPA + classic form pages) keep current behavior; pure-fetch API operators opt in.

package/lib/middleware/assetlinks.js

@@ -0,0 +1,97 @@
+"use strict";
+/**
+ * assetlinks middleware — emits Digital Asset Links at
+ * `/.well-known/assetlinks.json` per Google's Digital Asset Links
+ * spec (used by Trusted Web Activity / Android App Links / Smart
+ * Lock for Passwords / Web Authentication for Android, etc.).
+ *
+ *   var al = b.middleware.assetlinks({
+ *     statements: [
+ *       {
+ *         relation: ["delegate_permission/common.handle_all_urls"],
+ *         target: {
+ *           namespace:        "android_app",
+ *           package_name:     "com.example.app",
+ *           sha256_cert_fingerprints: ["AB:CD:..."],
+ *         },
+ *       },
+ *     ],
+ *   });
+ *   router.use(al);
+ *
+ * The framework JSON-serializes the statements array once at
+ * create() and serves with `Content-Type: application/json` per
+ * Google's spec. Operators with multiple linked apps include
+ * multiple statement entries.
+ */
+
+var lazyRequire = require("../lazy-require");
+var safeJson = require("../safe-json");
+var validateOpts = require("../validate-opts");
+var { defineClass } = require("../framework-error");
+
+var AssetlinksError = defineClass("AssetlinksError", { alwaysPermanent: true });
+
+var observability = lazyRequire(function () { return require("../observability"); });
+
+function create(opts) {
+  validateOpts.requireObject(opts, "middleware.assetlinks", AssetlinksError);
+  validateOpts(opts, ["statements", "audit"], "middleware.assetlinks");
+
+  if (!Array.isArray(opts.statements) || opts.statements.length === 0) {
+    throw new AssetlinksError("assetlinks/no-statements",
+      "middleware.assetlinks: opts.statements must be a non-empty array of statement objects");
+  }
+  for (var i = 0; i < opts.statements.length; i += 1) {
+    var stmt = opts.statements[i];
+    if (!stmt || typeof stmt !== "object" || Array.isArray(stmt)) {
+      throw new AssetlinksError("assetlinks/bad-statement",
+        "middleware.assetlinks: statements[" + i + "] must be a plain object");
+    }
+    if (!Array.isArray(stmt.relation) || stmt.relation.length === 0) {
+      throw new AssetlinksError("assetlinks/bad-statement",
+        "middleware.assetlinks: statements[" + i + "].relation must be a non-empty array");
+    }
+    if (!stmt.target || typeof stmt.target !== "object") {
+      throw new AssetlinksError("assetlinks/bad-statement",
+        "middleware.assetlinks: statements[" + i + "].target must be an object");
+    }
+  }
+
+  var body = safeJson.stringify(opts.statements, { space: 2 });
+  var bodyBuf = Buffer.from(body, "utf8");
+  var auditOn = opts.audit !== false;
+
+  return function assetlinksMiddleware(req, res, next) {
+    var url = req.url || "";
+    var qIdx = url.indexOf("?");
+    var path = qIdx === -1 ? url : url.slice(0, qIdx);
+    if (path !== "/.well-known/assetlinks.json") return next();
+    if (req.method !== "GET" && req.method !== "HEAD") {
+      var bodyMsg = "Method Not Allowed";
+      res.writeHead(405, {                                                       // allow:raw-byte-literal — HTTP 405 status
+        "Allow":          "GET, HEAD",
+        "Content-Type":   "text/plain; charset=utf-8",
+        "Content-Length": Buffer.byteLength(bodyMsg),
+      });
+      res.end(bodyMsg);
+      return;
+    }
+    res.writeHead(200, {                                                         // allow:raw-byte-literal — HTTP 200 status
+      "Content-Type":     "application/json; charset=utf-8",
+      "Content-Length":   bodyBuf.length,
+      "Cache-Control":    "public, max-age=86400",
+      "X-Content-Type-Options": "nosniff",
+    });
+    if (req.method === "HEAD") { res.end(); return; }
+    res.end(bodyBuf);
+    if (auditOn) {
+      try { observability().safeEvent("middleware.assetlinks.served", 1, {}); }
+      catch (_e) { /* obs best-effort */ }
+    }
+  };
+}
+
+module.exports = {
+  create: create,
+};

package/lib/middleware/index.js

@@ -17,6 +17,7 @@
  *   7. errorHandler     — must be LAST so it catches everything that throws
  */
 var apiEncrypt = require("./api-encrypt");
+var assetlinks = require("./assetlinks");
 var attachUser = require("./attach-user");
 var bearerAuth = require("./bearer-auth");
 var bodyParser = require("./body-parser");
@@ -45,6 +46,7 @@ var requireMethods = require("./require-methods");
 var securityHeaders = require("./security-headers");
 var securityTxt = require("./security-txt");
 var sse = require("./sse");
+var webAppManifest = require("./web-app-manifest");
 
 module.exports = {
   requestId:        requestId.create,
@@ -72,10 +74,12 @@ module.exports = {
   sse:              sse.create,
   requestLog:       requestLog.create,
   apiEncrypt:       apiEncrypt,
+  assetlinks:       assetlinks.create,
   dbRoleFor:        dbRoleFor.create,
   dpop:             dpop.create,
   hostAllowlist:    hostAllowlist.create,
   networkAllowlist: networkAllowlist.create,
+  webAppManifest:   webAppManifest.create,
 
   // Module exports for advanced use (constants, raw factory access)
   _modules: {
@@ -101,9 +105,11 @@ module.exports = {
     sse:              sse,
     requestLog:       requestLog,
     apiEncrypt:       apiEncrypt,
+    assetlinks:       assetlinks,
     dbRoleFor:        dbRoleFor,
     dpop:             dpop,
     hostAllowlist:    hostAllowlist,
     networkAllowlist: networkAllowlist,
+    webAppManifest:   webAppManifest,
   },
 };

package/lib/middleware/web-app-manifest.js

@@ -0,0 +1,111 @@
+"use strict";
+/**
+ * web-app-manifest middleware — emits the W3C Web App Manifest at
+ * `/manifest.webmanifest` (and `/manifest.json` when `alsoAtJsonPath`
+ * is true) per the W3C Web App Manifest specification.
+ *
+ *   var mf = b.middleware.webAppManifest({
+ *     name:        "Example App",
+ *     short_name:  "Example",
+ *     start_url:   "/",
+ *     display:     "standalone",
+ *     theme_color: "#1976d2",
+ *     background_color: "#ffffff",
+ *     icons: [
+ *       { src: "/icons/192.png", sizes: "192x192", type: "image/png" },
+ *       { src: "/icons/512.png", sizes: "512x512", type: "image/png" },
+ *     ],
+ *   });
+ *   router.use(mf);
+ *
+ * The manifest is JSON-serialized once at create() and served with
+ * `Content-Type: application/manifest+json` per the W3C spec.
+ *
+ * Per W3C — `name`, `start_url`, and at least one icon are required
+ * for an installable PWA. The framework throws at create() when any
+ * of those are missing.
+ */
+
+var lazyRequire = require("../lazy-require");
+var safeJson = require("../safe-json");
+var validateOpts = require("../validate-opts");
+var { defineClass } = require("../framework-error");
+
+var WebAppManifestError = defineClass("WebAppManifestError", { alwaysPermanent: true });
+
+var observability = lazyRequire(function () { return require("../observability"); });
+
+function _isPlainArray(x) { return Array.isArray(x); }
+
+function create(opts) {
+  validateOpts.requireObject(opts, "middleware.webAppManifest", WebAppManifestError);
+  // Allowlist subset of W3C-spec attributes operators commonly set.
+  // Anything outside the list throws at create — typos surface at boot.
+  validateOpts(opts, [
+    "name", "short_name", "description", "start_url", "scope",
+    "display", "display_override", "orientation",
+    "theme_color", "background_color",
+    "icons", "screenshots", "shortcuts",
+    "categories", "lang", "dir", "id",
+    "prefer_related_applications", "related_applications",
+    "alsoAtJsonPath", "audit",
+  ], "middleware.webAppManifest");
+
+  validateOpts.requireNonEmptyString(opts.name,
+    "middleware.webAppManifest: name", WebAppManifestError, "manifest/no-name");
+  validateOpts.requireNonEmptyString(opts.start_url,
+    "middleware.webAppManifest: start_url", WebAppManifestError, "manifest/no-start-url");
+  if (!_isPlainArray(opts.icons) || opts.icons.length === 0) {
+    throw new WebAppManifestError("manifest/no-icons",
+      "middleware.webAppManifest: icons array is required (W3C spec — at least one icon for installability)");
+  }
+
+  // Build the JSON body once at create.
+  var manifest = {};
+  var keys = Object.keys(opts).filter(function (k) {
+    return k !== "alsoAtJsonPath" && k !== "audit";
+  });
+  for (var i = 0; i < keys.length; i += 1) {
+    var k = keys[i];
+    if (opts[k] !== undefined && opts[k] !== null) manifest[k] = opts[k];
+  }
+  var body = safeJson.stringify(manifest, { space: 2 });
+  var bodyBuf = Buffer.from(body, "utf8");
+  var alsoAtJsonPath = opts.alsoAtJsonPath === true;
+  var auditOn = opts.audit !== false;
+
+  return function webAppManifestMiddleware(req, res, next) {
+    var url = req.url || "";
+    var qIdx = url.indexOf("?");
+    var path = qIdx === -1 ? url : url.slice(0, qIdx);
+    var matches = (path === "/manifest.webmanifest") ||
+                  (alsoAtJsonPath && path === "/manifest.json");
+    if (!matches) return next();
+    if (req.method !== "GET" && req.method !== "HEAD") {
+      var bodyMsg = "Method Not Allowed";
+      res.writeHead(405, {                                                       // allow:raw-byte-literal — HTTP 405 status
+        "Allow":          "GET, HEAD",
+        "Content-Type":   "text/plain; charset=utf-8",
+        "Content-Length": Buffer.byteLength(bodyMsg),
+      });
+      res.end(bodyMsg);
+      return;
+    }
+    res.writeHead(200, {                                                         // allow:raw-byte-literal — HTTP 200 status
+      "Content-Type":     "application/manifest+json",
+      "Content-Length":   bodyBuf.length,
+      "Cache-Control":    "public, max-age=86400",
+      "X-Content-Type-Options": "nosniff",
+    });
+    if (req.method === "HEAD") { res.end(); return; }
+    res.end(bodyBuf);
+    if (auditOn) {
+      try { observability().safeEvent("middleware.webAppManifest.served", 1, { path: path }); }
+      catch (_e) { /* obs best-effort */ }
+    }
+  };
+}
+
+module.exports = {
+  create: create,
+};

package/package.json

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

package/sbom.cyclonedx.json

@@ -2,10 +2,10 @@
   "$schema": "http://cyclonedx.org/schema/bom-1.5.schema.json",
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
-  "serialNumber": "urn:uuid:96ee5394-43c1-471e-98e9-f3b59c96f3e0",
+  "serialNumber": "urn:uuid:5980b589-6ae2-43c3-88ad-31cb87e43594",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-06T06:37:03.759Z",
+    "timestamp": "2026-05-06T06:50:00.974Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.7.87",
+      "bom-ref": "@blamejs/core@0.7.88",
       "type": "library",
       "name": "blamejs",
-      "version": "0.7.87",
+      "version": "0.7.88",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.7.87",
+      "purl": "pkg:npm/%40blamejs/core@0.7.88",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.7.87",
+      "ref": "@blamejs/core@0.7.88",
       "dependsOn": []
     }
   ]