@klnap/next-proxy-chain 1.0.0 → 1.0.1

package/README.md

@@ -1,52 +1,91 @@
-# `@repo/next-proxy-chain`
+# @klnap/next-proxy-chain
 
-Composable Next.js Edge proxy pipeline with pure Web API core, pass-through detection, context threading, header/cookie accumulation, and zero external runtime dependencies.
+> Composable Next.js 16+ Edge proxy and middleware rule chain with deterministic header/cookie accumulation, isolated per-request context, and a pure Web API core.
+
+[![npm version](https://img.shields.io/npm/v/@klnap/next-proxy-chain.svg)](https://www.npmjs.com/package/@klnap/next-proxy-chain)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-3178C6.svg)](https://www.typescriptlang.org/)
+[![Runtime: Edge / Node / Bun / Deno](https://img.shields.io/badge/Runtime-Edge%20%7C%20Node%20%7C%20Bun%20%7C%20Deno-black.svg)](https://bun.sh)
 
 ---
 
-## Key Features
+## Why `@klnap/next-proxy-chain`?
+
+Next.js 16 introduces the `proxy.ts` file convention to replace monolithic middleware files. In non-trivial production applications, middleware pipelines easily devolve into deeply nested wrappers, conflicting `Set-Cookie` headers, race conditions from stateful regular expressions, and leaked transport headers.
 
-- **Linear Pipeline Composition**: Order middleware steps clearly without nested wrapper hell.
-- **Pass-through Interoperability**: Transparently supports `NextResponse.next()` from third-party middlewares via `x-middleware-next: 1` detection.
-- **Per-request Context**: Type-safe, isolated `Map` context (`TContext`) threaded across all rules.
-- **Header & Cookie Accumulation**: Collects and merges request headers, response headers, and cookies across rules before writing to the outgoing response.
-- **Host & Path Scoping**: Declarative `include` / `exclude` routing rules with glob, RegExp, and next-intl locale support.
-- **Header Injection & Leak Protection**: Automatically filters internal `x-middleware-*` transport headers from client responses.
-- **100% Edge-Safe**: Built purely on standard Web APIs (`Headers`, `Map`, `Response`, `Request`).
+`@klnap/next-proxy-chain` solves this by providing:
+
+1. **Linear Pipeline Execution**: Run multiple independent proxy rules sequentially without nested wrapper callbacks.
+2. **Deterministic Header & Cookie Merging**: Combines request mutations (`x-middleware-request-*`), outgoing response headers, and multiple `Set-Cookie` directives without silent overwrites.
+3. **Pure Web API Core**: Zero Next.js dependencies in `@klnap/next-proxy-chain/core` — fully testable on Cloudflare Workers, Fastly, Bun, Deno, and standard Web runtimes.
+4. **Edge Runtime Hardening**: Strips stateful RegExp flags (`g`, `y`) to eliminate concurrent request cross-talk in multi-tenant edge workers, enforces per-rule timeouts, and protects against prototype pollution via `Map` context.
+5. **Header Poisoning Defense**: Protects client responses by stripping sensitive transport headers (`x-middleware-*`) and blocks unauthorized override of protected headers (`Host`, `Authorization`, `Connection`).
+
+---
+
+## Installation
+
+```bash
+# Using Bun
+bun add @klnap/next-proxy-chain
+
+# Using npm
+npm install @klnap/next-proxy-chain
+
+# Using pnpm
+pnpm add @klnap/next-proxy-chain
+
+# Using Yarn
+yarn add @klnap/next-proxy-chain
+```
 
 ---
 
 ## Quick Start
 
-### 1. Define Reusable Proxies
+### 1. Define Modular Proxy Rules
+
+Create self-contained proxy rules in your application:
 
-```ts
-import { defineProxy, next } from "@repo/next-proxy-chain"
+```typescript
+// src/proxies/request-id.ts
+import { defineProxy, next } from "@klnap/next-proxy-chain"
 
-// Request ID injector
 export const requestIdProxy = defineProxy("requestId", (req) => {
-  const id = crypto.randomUUID()
+  const requestId = req.headers.get("x-request-id") ?? crypto.randomUUID()
+
   return next({
-    request: { "x-request-id": id },
-    headers: { "x-request-id": id },
+    request: { "x-request-id": requestId },
+    headers: { "x-request-id": requestId },
   })
 })
+```
+
+```typescript
+// src/proxies/auth.ts
+import { defineProxy, next } from "@klnap/next-proxy-chain"
+import { NextResponse } from "next/server"
 
-// Authentication guard
 export const authProxy = defineProxy("auth", async (req, ctx) => {
-  const token = req.cookies.get("auth-token")?.value
+  const token = req.cookies.get("session_token")?.value
+
   if (!token) {
-    return NextResponse.redirect(new URL("/login", req.url))
+    const loginUrl = new URL("/login", req.url)
+    loginUrl.searchParams.set("from", req.nextUrl.pathname)
+    return NextResponse.redirect(loginUrl)
   }
-  ctx.set("userId", "user_123")
+
+  // Store user info in isolated per-request context
+  ctx.set("userId", "user_abc123")
   return next()
 })
 ```
 
-### 2. Assemble the Pipeline in `proxy.ts`
+### 2. Assemble Pipeline in `src/proxy.ts` (Next.js 16)
 
-```ts
-import { proxyChain, path } from "@repo/next-proxy-chain"
+```typescript
+// src/proxy.ts
+import { proxyChain, path } from "@klnap/next-proxy-chain"
 import { requestIdProxy } from "./proxies/request-id"
 import { authProxy } from "./proxies/auth"
 import { i18nProxy } from "./proxies/i18n"
@@ -54,11 +93,16 @@ import { i18nProxy } from "./proxies/i18n"
 const isDev = process.env.NODE_ENV !== "production"
 
 export default proxyChain({ debug: isDev }, [
+  // 1. Injects request ID on all incoming traffic
   requestIdProxy,
+
+  // 2. Guards dashboard routes, excluding public preview assets
   authProxy({
     include: path("/dashboard/*"),
-    exclude: path("/dashboard/public"),
+    exclude: path("/dashboard/public/*"),
   }),
+
+  // 3. Handles internationalization routing
   i18nProxy,
 ])
 
@@ -69,41 +113,103 @@ export const config = {
 
 ---
 
-## Scope Matching Rules
+## Route & Host Scoping
+
+Rules can be declaratively scoped by path, host, or combinations. Scoping evaluates exclusions first — if an exclusion matches, the rule is skipped immediately.
+
+```typescript
+import { defineProxy, path, host } from "@klnap/next-proxy-chain"
+
+// Scoped to specific path patterns on ANY host
+const adminRule = defineProxy("admin", handler, {
+  include: path("/admin/*"),
+})
+
+// Scoped to a specific domain or tenant
+const tenantRule = defineProxy("tenant", handler, {
+  include: { host: "app.example.com" },
+})
+
+// Scoped to specific path on a specific host
+const checkoutRule = defineProxy("checkout", handler, {
+  include: { host: "store.example.com", path: "/checkout/*" },
+})
+
+// Array of clauses (OR evaluation) with strict exclusions
+const apiRule = defineProxy("apiGuard", handler, {
+  include: [
+    path("/api/v1/*"),
+    { host: "api.example.com" },
+  ],
+  exclude: [
+    path("/api/v1/health"),
+    { host: "internal.example.com" },
+  ],
+})
+```
+
+---
+
+## Deterministic Header & Cookie Merging
 
-Scoping supports globs, RegExps, host matching, and combinations:
+When multiple rules in the chain mutate headers or cookies, `@klnap/next-proxy-chain` merges them deterministically:
 
-```ts
-// Path on any host
-include: path("/admin/*")
+- **Request Overrides (`next({ request: { ... } })`)**: Downstream rules and final page route handlers receive the accumulated mutated headers via Next.js request override encoding.
+- **Response Headers (`next({ headers: { ... } })`)**: Accumulated using last-write-wins strategy, written to the terminal response.
+- **Cookies (`Set-Cookie`)**: Multiple `Set-Cookie` directives across different rules are deduplicated by name and path attributes without dropping earlier cookies.
 
-// Any path on a specific host
-include: { host: "shop.localhost" }
+```typescript
+import { defineProxy, next } from "@klnap/next-proxy-chain"
 
-// Specific path on a specific host
-include: { host: "shop.localhost", path: "/checkout/*" }
+export const headerEnricher = defineProxy("enricher", () => {
+  return next({
+    request: {
+      "x-geo-region": "eu-central",
+    },
+    headers: {
+      "x-content-type-options": "nosniff",
+      "x-frame-options": "DENY",
+    },
+  })
+})
+```
+
+---
 
-// OR combinations
-include: [
-  path("/health"),
-  { host: "shop.localhost", path: "/checkout/*" },
-]
+## Pure Web API Core (`@klnap/next-proxy-chain/core`)
 
-// Exclude always wins
-exclude: { host: "museum.localhost" }
+For non-Next.js environments (Cloudflare Workers, Fastly Compute, Deno Deploy, Bun HTTP servers), use the pure core subpath:
+
+```typescript
+import {
+  createProxyContext,
+  mergeWrites,
+  withPaths,
+  next,
+  isNextResult,
+  toStatelessRegExp
+} from "@klnap/next-proxy-chain/core"
+
+// Zero dependencies on next/server — standard Fetch API only
+const context = createProxyContext()
 ```
 
 ---
 
-## Error Handling
+## Error Handling & Timeout Budgets
+
+Prevent unresponsive downstream authentication services or external APIs from blocking Edge execution:
 
-By default, any unhandled error inside a rule logs safely and returns an HTTP 500 (`safeInternalError`). You can supply a custom `onError` handler:
+```typescript
+import { proxyChain } from "@klnap/next-proxy-chain"
+import { NextResponse } from "next/server"
 
-```ts
 export default proxyChain(
   {
-    onError: (err, ruleIndex, req, ctx) => {
-      return new NextResponse("Service Unavailable", { status: 503 })
+    timeoutMs: 3000, // Global timeout budget per rule in milliseconds
+    onError: (error, ruleIndex, req, ctx) => {
+      console.error(`Rule at index ${ruleIndex} failed:`, error)
+      return new NextResponse("Service Temporarily Unavailable", { status: 503 })
     },
   },
   [
@@ -116,11 +222,29 @@ export default proxyChain(
 
 ## API Reference
 
-### Core Functions
+### Exported Functions (`@klnap/next-proxy-chain`)
+
+| Function | Description |
+| :--- | :--- |
+| `proxyChain(options?, rules)` | Assembles rules into a Next.js proxy/middleware handler. |
+| `defineProxy(name, fn, filter?)` | Factory creating a reusable, scope-aware proxy rule function. |
+| `withPaths(fn, filter)` | Wraps a raw proxy function with declarative path/host matching rules. |
+| `next(options?)` | Returns a continuation action with optional `{ request?, headers? }` mutations. |
+| `path(pattern)` | Helper compiling glob or RegExp string into a path matcher. |
+| `host(matcher)` | Helper compiling domain or RegExp matcher into a host matcher. |
+| `createProxyContext()` | Creates a clean, isolated `Map<string, unknown>` context. |
+| `decodeOverriddenRequestHeaders(headers)` | Extracts internal Next.js middleware request header overrides. |
+
+### Exported Types
+
+- `ProxyFn<TContext>`: Contract for individual proxy execution functions.
+- `ProxyRule<TContext>`: Composed rule containing execution handler and compiled scope filters.
+- `ProxyContext`: Isolated `Map<string, unknown>` instance passed to each rule.
+- `NextResult`: Continuation action containing mutation payloads.
+- `ProxyPathFilter`: Declarative configuration containing `include` and `exclude` clauses.
+
+---
+
+## License
 
-- `proxyChain(options?, rules)`: Combines rules into an Edge proxy handler.
-- `defineProxy(name?, fn)`: Creates a proxy function that can be called with `{ include, exclude }` to scope.
-- `withPaths(rule, filter)`: Scopes any rule function with path/host filters.
-- `next(options?)`: Signals pipeline continuation with optional `{ request?, headers? }` mutations.
-- `decodeOverriddenRequestHeaders(headers)`: Extracts Next.js middleware request header overrides.
-- `createProxyContext()`: Instantiates a fresh `Map` for per-request context.
+MIT © [klnap](https://github.com/klnap)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@klnap/next-proxy-chain",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Composable Next.js 16+ proxy rule chain with Edge-safe logging and a pure core (zero Next imports).",
   "license": "MIT",
   "author": "klnap",
@@ -46,7 +46,7 @@
     "clean": "rm -rf dist .turbo coverage node_modules"
   },
   "peerDependencies": {
-    "next": ">=15.0.0 || >=16.0.0"
+    "next": ">=16.0.0"
   },
   "devDependencies": {
     "@types/node": "^20",