specnav-middleware 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,33 @@
+# @specnav/middleware
+
+## 0.2.0
+
+### Minor Changes
+
+- Initial public release with trajectory prediction, 3-layer caching, DOM morphing, and all 19 audit bugs fixed.
+
+  Features:
+  - Trajectory-based prefetch with cursor prediction
+  - 3-layer cache (Memory/ServiceWorker/Edge)
+  - Surgical DOM morphing with scroll/focus preservation
+  - Speculative rendering in detached containers
+  - Navigation graph learning for pattern-based prefetch
+  - Adaptive mode with battery/network awareness
+  - Next.js Link component (drop-in replacement)
+  - Edge middleware with rate limiting and CSRF protection
+
+  Bug fixes:
+  - Fixed trajectory prediction actually triggering prefetch
+  - Fixed navigation graph self-to-self transitions
+  - Fixed cache blocking Next.js **NEXT_DATA** scripts
+  - Fixed onNavigateEnd callback implementation
+  - Fixed middleware same-origin bypass
+  - Fixed null engines on first render
+  - Fixed LRU cache duplicate entries
+  - Fixed cache exclusion substring matching
+  - Fixed async adaptive initialization race
+  - Fixed duplicate Link unregistration
+  - Fixed morph refocus without containment check
+  - Fixed navigation timing polling
+  - Fixed cache hit rate tracking
+  - And 6 more fixes (see BUG_FIXES.md)

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 specnav contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.cjs

@@ -0,0 +1,56 @@
+'use strict';
+
+var server = require('next/server');
+
+// src/index.ts
+var rateLimitMap = /* @__PURE__ */ new Map();
+function checkRateLimit(ip, limit = 100, windowMs = 6e4) {
+  const now = Date.now();
+  const record = rateLimitMap.get(ip);
+  if (!record || now > record.resetAt) {
+    rateLimitMap.set(ip, { count: 1, resetAt: now + windowMs });
+    return true;
+  }
+  if (record.count >= limit) {
+    return false;
+  }
+  record.count++;
+  return true;
+}
+function specnavMiddleware(request) {
+  const isSpecnav = request.headers.get("x-specnav") === "1";
+  if (!isSpecnav) return null;
+  const ip = request.headers.get("x-forwarded-for")?.split(",")[0] || request.headers.get("x-real-ip") || "unknown";
+  if (!checkRateLimit(ip)) {
+    return new server.NextResponse("Too Many Requests", { status: 429 });
+  }
+  const origin = request.headers.get("origin");
+  const referer = request.headers.get("referer");
+  if (!origin && !referer) {
+    return new server.NextResponse("Forbidden", { status: 403 });
+  }
+  const requestOrigin = origin || new URL(referer).origin;
+  const serverOrigin = new URL(request.url).origin;
+  if (requestOrigin !== serverOrigin) {
+    return new server.NextResponse("Forbidden", { status: 403 });
+  }
+  const headers = new Headers(request.headers);
+  headers.set("x-specnav-partial", "1");
+  return server.NextResponse.next({
+    request: {
+      headers
+    }
+  });
+}
+function isSpecnavRequest(request) {
+  return request.headers.get("x-specnav") === "1";
+}
+function isPartialRequest(request) {
+  return request.headers.get("x-specnav-partial") === "1";
+}
+
+exports.isPartialRequest = isPartialRequest;
+exports.isSpecnavRequest = isSpecnavRequest;
+exports.specnavMiddleware = specnavMiddleware;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":["NextResponse"],"mappings":";;;;;AAOA,IAAM,YAAA,uBAAmB,GAAA,EAAgD;AAEzE,SAAS,cAAA,CAAe,EAAA,EAAY,KAAA,GAAQ,GAAA,EAAK,WAAW,GAAA,EAAgB;AAC1E,EAAA,MAAM,GAAA,GAAM,KAAK,GAAA,EAAI;AACrB,EAAA,MAAM,MAAA,GAAS,YAAA,CAAa,GAAA,CAAI,EAAE,CAAA;AAElC,EAAA,IAAI,CAAC,MAAA,IAAU,GAAA,GAAM,MAAA,CAAO,OAAA,EAAS;AACnC,IAAA,YAAA,CAAa,GAAA,CAAI,IAAI,EAAE,KAAA,EAAO,GAAG,OAAA,EAAS,GAAA,GAAM,UAAU,CAAA;AAC1D,IAAA,OAAO,IAAA;AAAA,EACT;AAEA,EAAA,IAAI,MAAA,CAAO,SAAS,KAAA,EAAO;AACzB,IAAA,OAAO,KAAA;AAAA,EACT;AAEA,EAAA,MAAA,CAAO,KAAA,EAAA;AACP,EAAA,OAAO,IAAA;AACT;AAEO,SAAS,kBAAkB,OAAA,EAA2C;AAC3E,EAAA,MAAM,SAAA,GAAY,OAAA,CAAQ,OAAA,CAAQ,GAAA,CAAI,WAAW,CAAA,KAAM,GAAA;AAEvD,EAAA,IAAI,CAAC,WAAW,OAAO,IAAA;AAGvB,EAAA,MAAM,EAAA,GAAK,OAAA,CAAQ,OAAA,CAAQ,GAAA,CAAI,iBAAiB,CAAA,EAAG,KAAA,CAAM,GAAG,CAAA,CAAE,CAAC,CAAA,IACpD,OAAA,CAAQ,OAAA,CAAQ,GAAA,CAAI,WAAW,CAAA,IAC/B,SAAA;AACX,EAAA,IAAI,CAAC,cAAA,CAAe,EAAE,CAAA,EAAG;AACvB,IAAA,OAAO,IAAIA,mBAAA,CAAa,mBAAA,EAAqB,EAAE,MAAA,EAAQ,KAAK,CAAA;AAAA,EAC9D;AAGA,EAAA,MAAM,MAAA,GAAS,OAAA,CAAQ,OAAA,CAAQ,GAAA,CAAI,QAAQ,CAAA;AAC3C,EAAA,MAAM,OAAA,GAAU,OAAA,CAAQ,OAAA,CAAQ,GAAA,CAAI,SAAS,CAAA;AAE7C,EAAA,IAAI,CAAC,MAAA,IAAU,CAAC,OAAA,EAAS;AACvB,IAAA,OAAO,IAAIA,mBAAA,CAAa,WAAA,EAAa,EAAE,MAAA,EAAQ,KAAK,CAAA;AAAA,EACtD;AAEA,EAAA,MAAM,aAAA,GAAgB,MAAA,IAAU,IAAI,GAAA,CAAI,OAAQ,CAAA,CAAE,MAAA;AAClD,EAAA,MAAM,YAAA,GAAe,IAAI,GAAA,CAAI,OAAA,CAAQ,GAAG,CAAA,CAAE,MAAA;AAE1C,EAAA,IAAI,kBAAkB,YAAA,EAAc;AAClC,IAAA,OAAO,IAAIA,mBAAA,CAAa,WAAA,EAAa,EAAE,MAAA,EAAQ,KAAK,CAAA;AAAA,EACtD;AAGA,EAAA,MAAM,OAAA,GAAU,IAAI,OAAA,CAAQ,OAAA,CAAQ,OAAO,CAAA;AAC3C,EAAA,OAAA,CAAQ,GAAA,CAAI,qBAAqB,GAAG,CAAA;AAEpC,EAAA,OAAOA,oBAAa,IAAA,CAAK;AAAA,IACvB,OAAA,EAAS;AAAA,MACP;AAAA;AACF,GACD,CAAA;AACH;AAEO,SAAS,iBAAiB,OAAA,EAA+B;AAC9D,EAAA,OAAO,OAAA,CAAQ,OAAA,CAAQ,GAAA,CAAI,WAAW,CAAA,KAAM,GAAA;AAC9C;AAEO,SAAS,iBAAiB,OAAA,EAA+B;AAC9D,EAAA,OAAO,OAAA,CAAQ,OAAA,CAAQ,GAAA,CAAI,mBAAmB,CAAA,KAAM,GAAA;AACtD","file":"index.cjs","sourcesContent":["import { NextResponse } from \"next/server\";\nimport type { NextRequest } from \"next/server\";\n\n// Simple in-memory rate limiter\n// ⚠️  WARNING: This rate limiter is NOT effective on serverless platforms (Vercel Edge, AWS Lambda, etc.)\n// where each cold start creates a fresh module scope, resetting the Map. For production serverless use,\n// replace with a persistent store like Redis, Upstash, Vercel KV, or a distributed rate limiting service.\nconst rateLimitMap = new Map<string, { count: number; resetAt: number }>();\n\nfunction checkRateLimit(ip: string, limit = 100, windowMs = 60000): boolean {\n  const now = Date.now();\n  const record = rateLimitMap.get(ip);\n\n  if (!record || now > record.resetAt) {\n    rateLimitMap.set(ip, { count: 1, resetAt: now + windowMs });\n    return true;\n  }\n\n  if (record.count >= limit) {\n    return false;\n  }\n\n  record.count++;\n  return true;\n}\n\nexport function specnavMiddleware(request: NextRequest): NextResponse | null {\n  const isSpecnav = request.headers.get(\"x-specnav\") === \"1\";\n\n  if (!isSpecnav) return null;\n\n  // Rate limiting\n  const ip = request.headers.get(\"x-forwarded-for\")?.split(\",\")[0] || \n             request.headers.get(\"x-real-ip\") || \n             \"unknown\";\n  if (!checkRateLimit(ip)) {\n    return new NextResponse(\"Too Many Requests\", { status: 429 });\n  }\n\n  // Security: Verify same-origin (deny if headers missing)\n  const origin = request.headers.get(\"origin\");\n  const referer = request.headers.get(\"referer\");\n  \n  if (!origin && !referer) {\n    return new NextResponse(\"Forbidden\", { status: 403 });\n  }\n  \n  const requestOrigin = origin || new URL(referer!).origin;\n  const serverOrigin = new URL(request.url).origin;\n  \n  if (requestOrigin !== serverOrigin) {\n    return new NextResponse(\"Forbidden\", { status: 403 });\n  }\n\n  // Clone request and add internal header for route handlers\n  const headers = new Headers(request.headers);\n  headers.set(\"x-specnav-partial\", \"1\");\n\n  return NextResponse.next({\n    request: {\n      headers,\n    },\n  });\n}\n\nexport function isSpecnavRequest(request: NextRequest): boolean {\n  return request.headers.get(\"x-specnav\") === \"1\";\n}\n\nexport function isPartialRequest(request: NextRequest): boolean {\n  return request.headers.get(\"x-specnav-partial\") === \"1\";\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,7 @@
+import { NextRequest, NextResponse } from 'next/server';
+
+declare function specnavMiddleware(request: NextRequest): NextResponse | null;
+declare function isSpecnavRequest(request: NextRequest): boolean;
+declare function isPartialRequest(request: NextRequest): boolean;
+
+export { isPartialRequest, isSpecnavRequest, specnavMiddleware };

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+import { NextRequest, NextResponse } from 'next/server';
+
+declare function specnavMiddleware(request: NextRequest): NextResponse | null;
+declare function isSpecnavRequest(request: NextRequest): boolean;
+declare function isPartialRequest(request: NextRequest): boolean;
+
+export { isPartialRequest, isSpecnavRequest, specnavMiddleware };

package/dist/index.js

@@ -0,0 +1,52 @@
+import { NextResponse } from 'next/server';
+
+// src/index.ts
+var rateLimitMap = /* @__PURE__ */ new Map();
+function checkRateLimit(ip, limit = 100, windowMs = 6e4) {
+  const now = Date.now();
+  const record = rateLimitMap.get(ip);
+  if (!record || now > record.resetAt) {
+    rateLimitMap.set(ip, { count: 1, resetAt: now + windowMs });
+    return true;
+  }
+  if (record.count >= limit) {
+    return false;
+  }
+  record.count++;
+  return true;
+}
+function specnavMiddleware(request) {
+  const isSpecnav = request.headers.get("x-specnav") === "1";
+  if (!isSpecnav) return null;
+  const ip = request.headers.get("x-forwarded-for")?.split(",")[0] || request.headers.get("x-real-ip") || "unknown";
+  if (!checkRateLimit(ip)) {
+    return new NextResponse("Too Many Requests", { status: 429 });
+  }
+  const origin = request.headers.get("origin");
+  const referer = request.headers.get("referer");
+  if (!origin && !referer) {
+    return new NextResponse("Forbidden", { status: 403 });
+  }
+  const requestOrigin = origin || new URL(referer).origin;
+  const serverOrigin = new URL(request.url).origin;
+  if (requestOrigin !== serverOrigin) {
+    return new NextResponse("Forbidden", { status: 403 });
+  }
+  const headers = new Headers(request.headers);
+  headers.set("x-specnav-partial", "1");
+  return NextResponse.next({
+    request: {
+      headers
+    }
+  });
+}
+function isSpecnavRequest(request) {
+  return request.headers.get("x-specnav") === "1";
+}
+function isPartialRequest(request) {
+  return request.headers.get("x-specnav-partial") === "1";
+}
+
+export { isPartialRequest, isSpecnavRequest, specnavMiddleware };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":";;;AAOA,IAAM,YAAA,uBAAmB,GAAA,EAAgD;AAEzE,SAAS,cAAA,CAAe,EAAA,EAAY,KAAA,GAAQ,GAAA,EAAK,WAAW,GAAA,EAAgB;AAC1E,EAAA,MAAM,GAAA,GAAM,KAAK,GAAA,EAAI;AACrB,EAAA,MAAM,MAAA,GAAS,YAAA,CAAa,GAAA,CAAI,EAAE,CAAA;AAElC,EAAA,IAAI,CAAC,MAAA,IAAU,GAAA,GAAM,MAAA,CAAO,OAAA,EAAS;AACnC,IAAA,YAAA,CAAa,GAAA,CAAI,IAAI,EAAE,KAAA,EAAO,GAAG,OAAA,EAAS,GAAA,GAAM,UAAU,CAAA;AAC1D,IAAA,OAAO,IAAA;AAAA,EACT;AAEA,EAAA,IAAI,MAAA,CAAO,SAAS,KAAA,EAAO;AACzB,IAAA,OAAO,KAAA;AAAA,EACT;AAEA,EAAA,MAAA,CAAO,KAAA,EAAA;AACP,EAAA,OAAO,IAAA;AACT;AAEO,SAAS,kBAAkB,OAAA,EAA2C;AAC3E,EAAA,MAAM,SAAA,GAAY,OAAA,CAAQ,OAAA,CAAQ,GAAA,CAAI,WAAW,CAAA,KAAM,GAAA;AAEvD,EAAA,IAAI,CAAC,WAAW,OAAO,IAAA;AAGvB,EAAA,MAAM,EAAA,GAAK,OAAA,CAAQ,OAAA,CAAQ,GAAA,CAAI,iBAAiB,CAAA,EAAG,KAAA,CAAM,GAAG,CAAA,CAAE,CAAC,CAAA,IACpD,OAAA,CAAQ,OAAA,CAAQ,GAAA,CAAI,WAAW,CAAA,IAC/B,SAAA;AACX,EAAA,IAAI,CAAC,cAAA,CAAe,EAAE,CAAA,EAAG;AACvB,IAAA,OAAO,IAAI,YAAA,CAAa,mBAAA,EAAqB,EAAE,MAAA,EAAQ,KAAK,CAAA;AAAA,EAC9D;AAGA,EAAA,MAAM,MAAA,GAAS,OAAA,CAAQ,OAAA,CAAQ,GAAA,CAAI,QAAQ,CAAA;AAC3C,EAAA,MAAM,OAAA,GAAU,OAAA,CAAQ,OAAA,CAAQ,GAAA,CAAI,SAAS,CAAA;AAE7C,EAAA,IAAI,CAAC,MAAA,IAAU,CAAC,OAAA,EAAS;AACvB,IAAA,OAAO,IAAI,YAAA,CAAa,WAAA,EAAa,EAAE,MAAA,EAAQ,KAAK,CAAA;AAAA,EACtD;AAEA,EAAA,MAAM,aAAA,GAAgB,MAAA,IAAU,IAAI,GAAA,CAAI,OAAQ,CAAA,CAAE,MAAA;AAClD,EAAA,MAAM,YAAA,GAAe,IAAI,GAAA,CAAI,OAAA,CAAQ,GAAG,CAAA,CAAE,MAAA;AAE1C,EAAA,IAAI,kBAAkB,YAAA,EAAc;AAClC,IAAA,OAAO,IAAI,YAAA,CAAa,WAAA,EAAa,EAAE,MAAA,EAAQ,KAAK,CAAA;AAAA,EACtD;AAGA,EAAA,MAAM,OAAA,GAAU,IAAI,OAAA,CAAQ,OAAA,CAAQ,OAAO,CAAA;AAC3C,EAAA,OAAA,CAAQ,GAAA,CAAI,qBAAqB,GAAG,CAAA;AAEpC,EAAA,OAAO,aAAa,IAAA,CAAK;AAAA,IACvB,OAAA,EAAS;AAAA,MACP;AAAA;AACF,GACD,CAAA;AACH;AAEO,SAAS,iBAAiB,OAAA,EAA+B;AAC9D,EAAA,OAAO,OAAA,CAAQ,OAAA,CAAQ,GAAA,CAAI,WAAW,CAAA,KAAM,GAAA;AAC9C;AAEO,SAAS,iBAAiB,OAAA,EAA+B;AAC9D,EAAA,OAAO,OAAA,CAAQ,OAAA,CAAQ,GAAA,CAAI,mBAAmB,CAAA,KAAM,GAAA;AACtD","file":"index.js","sourcesContent":["import { NextResponse } from \"next/server\";\nimport type { NextRequest } from \"next/server\";\n\n// Simple in-memory rate limiter\n// ⚠️  WARNING: This rate limiter is NOT effective on serverless platforms (Vercel Edge, AWS Lambda, etc.)\n// where each cold start creates a fresh module scope, resetting the Map. For production serverless use,\n// replace with a persistent store like Redis, Upstash, Vercel KV, or a distributed rate limiting service.\nconst rateLimitMap = new Map<string, { count: number; resetAt: number }>();\n\nfunction checkRateLimit(ip: string, limit = 100, windowMs = 60000): boolean {\n  const now = Date.now();\n  const record = rateLimitMap.get(ip);\n\n  if (!record || now > record.resetAt) {\n    rateLimitMap.set(ip, { count: 1, resetAt: now + windowMs });\n    return true;\n  }\n\n  if (record.count >= limit) {\n    return false;\n  }\n\n  record.count++;\n  return true;\n}\n\nexport function specnavMiddleware(request: NextRequest): NextResponse | null {\n  const isSpecnav = request.headers.get(\"x-specnav\") === \"1\";\n\n  if (!isSpecnav) return null;\n\n  // Rate limiting\n  const ip = request.headers.get(\"x-forwarded-for\")?.split(\",\")[0] || \n             request.headers.get(\"x-real-ip\") || \n             \"unknown\";\n  if (!checkRateLimit(ip)) {\n    return new NextResponse(\"Too Many Requests\", { status: 429 });\n  }\n\n  // Security: Verify same-origin (deny if headers missing)\n  const origin = request.headers.get(\"origin\");\n  const referer = request.headers.get(\"referer\");\n  \n  if (!origin && !referer) {\n    return new NextResponse(\"Forbidden\", { status: 403 });\n  }\n  \n  const requestOrigin = origin || new URL(referer!).origin;\n  const serverOrigin = new URL(request.url).origin;\n  \n  if (requestOrigin !== serverOrigin) {\n    return new NextResponse(\"Forbidden\", { status: 403 });\n  }\n\n  // Clone request and add internal header for route handlers\n  const headers = new Headers(request.headers);\n  headers.set(\"x-specnav-partial\", \"1\");\n\n  return NextResponse.next({\n    request: {\n      headers,\n    },\n  });\n}\n\nexport function isSpecnavRequest(request: NextRequest): boolean {\n  return request.headers.get(\"x-specnav\") === \"1\";\n}\n\nexport function isPartialRequest(request: NextRequest): boolean {\n  return request.headers.get(\"x-specnav-partial\") === \"1\";\n}\n"]}

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "specnav-middleware",
+  "version": "0.2.0",
+  "description": "Next.js Edge middleware for specnav with rate limiting, CSRF protection, and partial response rendering",
+  "license": "MIT",
+  "author": "Abraham",
+  "homepage": "https://github.com/Robini908/specnav#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Robini908/specnav.git",
+    "directory": "packages/middleware"
+  },
+  "bugs": {
+    "url": "https://github.com/Robini908/specnav/issues"
+  },
+  "keywords": [
+    "nextjs",
+    "next.js",
+    "middleware",
+    "edge",
+    "partial-response",
+    "rate-limiting",
+    "csrf"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "peerDependencies": {
+    "next": ">=14.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "next": "^15.0.0",
+    "tsup": "^8.0.2",
+    "typescript": "^5.8.0",
+    "vitest": "^2.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  }
+}