@klnap/next-proxy-chain 1.0.0 → 1.0.2

package/dist/index.d.cts

@@ -1,31 +1,105 @@
 import { NextRequest, NextFetchEvent, NextResponse } from 'next/server';
-import { ProxyContext, MergeStrategy, ChainLogger, RequestHeaderPolicy, NextResult, ProxyPathFilter, BaseProxyRule } from './core.cjs';
-export { CompiledScope, DEFAULT_BLOCKED_REQUEST_HEADERS, EntryWrite, HostMatcher, LogLevel, NEXT, NextOptions, PathMatcher, PathOptions, PipelineOutcome, ProxyResult, RouteScopeInput, RouteScopeList, RuleTimeoutError, applyMergedToResponse, assertIncludeExcludeNoOverlap, compileScopes, cookieItemsFromHeaders, createConsoleLogger, createProxyContext, decodeOverriddenRequestHeaders, formatPipelineLine, headersDiffer, host, isNextResult, isRequestHeaderAllowed, listSetCookie, mergeRequestHeaderOverrides, mergeWrites, next, normalizeHost, parseCookieName, path, pathMatches, responseHeaderItems, ruleLabel, ruleMatches, toPathRegex, toRule, toStatelessRegExp, withPaths, withRuleTimeout } from './core.cjs';
 
 /**
- * A single proxy step.
- *
- * Contract:
- * - `return` / `undefined` — continue with no mutations
- * - `return next({ request?, headers? })` — continue with mutations
- * - `return Response | NextResponse` — if NextResponse.next() or NextResponse.rewrite(), chain continues with mutations; otherwise terminates after merge
- *
- * Third-party middleware (e.g. next-intl) should run **last** and return its
- * Response directly; any terminal Response terminates the chain after merge.
+ * Unique symbol identifying an explicit continue action in the proxy chain pipeline.
+ */
+declare const NEXT: unique symbol;
+/**
+ * Protected request headers that cannot be rewritten unless explicitly permitted by policy.
+ */
+declare const DEFAULT_BLOCKED_REQUEST_HEADERS: readonly string[];
+
+/**
+ * Configuration options for chain continuation.
+ */
+type NextOptions = {
+    /** Request header overrides visible to downstream rules and handlers. */
+    request?: HeadersInit;
+    /** Response headers merged into the final outgoing response. */
+    headers?: HeadersInit;
+};
+/**
+ * Continuation token indicating the pipeline should proceed to subsequent rules.
+ */
+type NextResult = NextOptions & {
+    readonly [NEXT]: true;
+};
+/**
+ * Shared state for an individual request pipeline execution.
+ * Backed by Map to eliminate prototype-pollution risks.
+ */
+type ProxyContext = Map<string, unknown>;
+type ProxyResult<TResponse = NextResponse | Response> = TResponse | NextResult | undefined | void;
+type PathMatcher = RegExp | string;
+type PathOptions = {
+    /** Optional locale prefixes for path matching. */
+    locales?: readonly string[];
+};
+type HostMatcher = string | RegExp | readonly (string | RegExp)[];
+/**
+ * Scoping configuration for rule inclusion or exclusion.
+ */
+type RouteScopeInput = PathMatcher | {
+    host: HostMatcher;
+    path?: PathMatcher | PathMatcher[];
+} | {
+    path: PathMatcher | PathMatcher[];
+    host?: HostMatcher;
+};
+type RouteScopeList = RouteScopeInput | RouteScopeInput[];
+/** Compiled route scope evaluated during request execution. */
+type CompiledScope = {
+    host?: RegExp;
+    path?: RegExp;
+};
+interface BaseProxyRule<TFn> {
+    run: TFn;
+    include?: CompiledScope[];
+    exclude?: CompiledScope[];
+    name?: string;
+}
+type ProxyPathFilter = {
+    include?: RouteScopeList;
+    exclude?: RouteScopeList;
+    name?: string;
+    pathOptions?: PathOptions;
+};
+/**
+ * A single proxy execution function.
  */
 type ProxyFn<TContext = ProxyContext> = (req: NextRequest, ctx: TContext, event: NextFetchEvent) => NextResponse | Response | NextResult | undefined | void | Promise<NextResponse | Response | NextResult | undefined | void>;
 type ProxyRule<TContext = ProxyContext> = BaseProxyRule<ProxyFn<TContext>>;
-type Entry<TContext> = ProxyFn<TContext> | ProxyRule<TContext>;
 type DefinedProxy<TContext = ProxyContext> = ProxyFn<TContext> & ((filter: ProxyPathFilter) => ProxyRule<TContext>);
-/**
- * Define a reusable proxy. Call with a path filter to scope it.
- *
- * @example
- * defineProxy("auth", (req, ctx) => next())
- * demoAuthProxy({ include: path("/admin/*") })
- */
-declare function defineProxy<TContext = ProxyContext>(run: ProxyFn<TContext>): DefinedProxy<TContext>;
-declare function defineProxy<TContext = ProxyContext>(name: string, run: ProxyFn<TContext>): DefinedProxy<TContext>;
+type Entry<TContext = ProxyContext> = ProxyFn<TContext> | ProxyRule<TContext>;
+type MergeStrategy = "last-write-wins" | "first-write-wins" | ((key: string, existing: string, incoming: string) => string | null);
+interface EntryWrite {
+    ruleIndex: number;
+    ruleName: string;
+    items: Map<string, string>;
+}
+type LogLevel = "debug" | "info" | "warn" | "error";
+interface ChainLogger {
+    debug: (metaOrMsg: unknown, maybeMsg?: string) => void;
+    info: (metaOrMsg: unknown, maybeMsg?: string) => void;
+    warn: (metaOrMsg: unknown, maybeMsg?: string) => void;
+    error: (metaOrMsg: unknown, maybeMsg?: string) => void;
+}
+type PipelineOutcome = {
+    kind: "passed";
+    duration: number;
+} | {
+    kind: "next";
+    duration: number;
+    headers: number;
+} | {
+    kind: "stop";
+    duration: number;
+    status: number;
+};
+interface RequestHeaderPolicy {
+    blocked?: readonly string[];
+    allowed?: readonly string[];
+}
 interface ChainConfig<TContext = ProxyContext> {
     createContext: (req: NextRequest, event: NextFetchEvent) => TContext;
     cookieMergeStrategy: MergeStrategy;
@@ -33,33 +107,179 @@ interface ChainConfig<TContext = ProxyContext> {
     onError?: (err: unknown, ruleIndex: number, req: NextRequest, ctx: TContext) => NextResponse | Response | undefined | void | Promise<NextResponse | Response | undefined | void>;
     debug: boolean;
     logger: ChainLogger;
-    /** Per-rule wall-clock limit in ms. `0` disables. */
+    /** Maximum wall-clock execution time per rule in milliseconds. 0 disables timeout. */
     ruleTimeoutMs: number;
     requestHeaderPolicy: RequestHeaderPolicy;
-    /** Throw an error if platform does not support request header overrides. Defaults to false (logs warning). */
+    /** Throw an error on startup if the runtime platform does not support request header overrides. */
     strictOverrideCheck?: boolean;
 }
 type ProxyChainOptions<TContext = ProxyContext> = Partial<ChainConfig<TContext>>;
+
+/**
+ * Creates an isolated per-request context instance.
+ * Backed by Map to eliminate prototype pollution risks.
+ */
+declare function createProxyContext(): ProxyContext;
+
+/**
+ * Strips sticky and global flags (g, y) from RegExp instances.
+ * On Edge runtimes, compiled regex instances can be shared across requests;
+ * sticky and global flags mutate stateful indices, causing non-deterministic matching.
+ */
+declare function toStatelessRegExp(re: RegExp): RegExp;
+/**
+ * Builds a compiled Host matcher RegExp from domain names, wildcards, or regex patterns.
+ */
+declare function host(matcher: HostMatcher): RegExp;
+/**
+ * Compiles a path pattern (glob string, param pattern, or RegExp) into a stateless regular expression.
+ */
+declare function path(pattern: string | RegExp, options?: PathOptions): RegExp;
+declare function toPathRegex(matcher: PathMatcher | PathMatcher[], options?: PathOptions): RegExp;
+/**
+ * Compiles route scoping declarations into normalized regex clauses.
+ */
+declare function compileScopes(input: RouteScopeList | undefined, pathOptions?: PathOptions): CompiledScope[] | undefined;
+declare function toRule<TFn>(entry: TFn | BaseProxyRule<TFn>): BaseProxyRule<TFn>;
+declare function ruleLabel<TFn>(rule: BaseProxyRule<TFn>, index: number): string;
+/**
+ * Decorates a proxy entry with declarative path and host inclusion/exclusion filters.
+ */
+declare function withPaths<TFn>(entry: TFn | BaseProxyRule<TFn>, filter: ProxyPathFilter): BaseProxyRule<TFn>;
+/**
+ * Determines whether a given request matches a rule's scoping constraints.
+ */
+declare function ruleMatches<TFn>(pathname: string, hostname: string | null, rule: BaseProxyRule<TFn>): boolean;
+declare function pathMatches<TFn>(pathname: string, rule: BaseProxyRule<TFn>): boolean;
+/**
+ * Normalizes Host or X-Forwarded-Host header values to lower-case hostname without port.
+ */
+declare function normalizeHost(raw: string | null | undefined): string | null;
+/**
+ * Validates that an identical scope is not declared simultaneously in include and exclude.
+ */
+declare function assertIncludeExcludeNoOverlap(include: CompiledScope[] | undefined, exclude: CompiledScope[] | undefined, label: string): void;
+
+/**
+ * Converts HeadersInit or undefined to a standard Web Headers instance.
+ */
+declare function headersInitToHeaders(init?: HeadersInit): Headers;
+/**
+ * Compares two Headers instances to determine if overrides contain differences.
+ */
+declare function headersDiffer(base: Headers, overrides: Headers): boolean;
+/**
+ * Checks whether a request header is permitted to be mutated under the configured policy.
+ */
+declare function isRequestHeaderAllowed(name: string, policy?: RequestHeaderPolicy): boolean;
+/**
+ * Merges new request header overrides into the target Headers instance, filtering prohibited headers.
+ */
+declare function mergeRequestHeaderOverrides(target: Headers, overrides: Headers, policy?: RequestHeaderPolicy): {
+    applied: number;
+    dropped: string[];
+};
+/**
+ * Extracts cookie name from a raw Set-Cookie directive.
+ */
+declare function parseCookieName(setCookie: string): string;
+/**
+ * Extracts all Set-Cookie directives using standard getSetCookie() when available.
+ */
+declare function listSetCookie(headers: Headers): string[];
+/**
+ * Maps cookie name to Set-Cookie header value from a Headers instance.
+ */
+declare function cookieItemsFromHeaders(headers: Headers): Map<string, string>;
+/**
+ * Filters out Set-Cookie and internal transport headers (x-middleware-*) from response headers.
+ */
+declare function responseHeaderItems(headers: Headers): Map<string, string>;
+/**
+ * Decodes Next.js request header overrides encoded into response headers.
+ */
+declare function decodeOverriddenRequestHeaders(headers: Headers): Headers;
+/**
+ * Deterministically merges writes across rules based on configured strategy.
+ */
+declare function mergeWrites(writes: EntryWrite[], strategy: MergeStrategy, onConflict?: (key: string, winner: string, loser: string) => void): Map<string, string>;
+/**
+ * Applies merged headers and deduplicated cookies onto an outgoing response.
+ */
+declare function applyMergedToResponse(res: Response, headers: Map<string, string>, cookies: Map<string, string>): void;
+
+/**
+ * Creates a continuation action instructing the proxy chain to proceed to subsequent rules.
+ *
+ * @param options - Optional request and response header mutations.
+ * @returns NextResult token indicating pipeline continuation.
+ */
+declare function next(options?: NextOptions): NextResult;
+/**
+ * Type guard verifying whether a returned value is a proxy continuation token.
+ *
+ * @param value - Value to test.
+ * @returns True if value is a NextResult continuation token.
+ */
+declare function isNextResult(value: unknown): value is NextResult;
+
+declare function createConsoleLogger(minLevel?: LogLevel): ChainLogger;
+/**
+ * Formats a single structured log line for an executed proxy rule.
+ */
+declare function formatPipelineLine(input: {
+    method: string;
+    path: string;
+    name: string;
+    traceId?: string;
+    outcome: PipelineOutcome;
+}): string;
+
+declare class RuleTimeoutError extends Error {
+    readonly ruleName: string;
+    readonly timeoutMs: number;
+    constructor(ruleName: string, timeoutMs: number);
+}
+/**
+ * Enforces a strict execution time budget on an asynchronous rule operation.
+ */
+declare function withRuleTimeout<T>(promise: Promise<T>, timeoutMs: number | undefined, ruleName: string): Promise<T>;
+
 declare function safeInternalError(): NextResponse;
-/** Assert once per process at construction time that NextResponse.next() supports request header overrides. */
 declare function assertOverrideMechanismSupported(strict?: boolean): boolean;
+type ResolvedOutcome = {
+    kind: "continue";
+    request?: Headers;
+    responseHeaders: Map<string, string>;
+    cookies: Map<string, string>;
+    rewriteUrl?: string;
+} | {
+    kind: "stop";
+    response: NextResponse | Response;
+};
+declare function resolveRuleResult(res: NextResponse | Response | NextResult | undefined | void, requestHeaderPolicy: RequestHeaderPolicy, logger: ChainLogger, debug: boolean): ResolvedOutcome;
+declare function finalizeResponse(res: NextResponse | Response, headerWrites: EntryWrite[], cookieWrites: EntryWrite[], headerStrategy: MergeStrategy, cookieStrategy: MergeStrategy, logger: ChainLogger, debug: boolean): NextResponse | Response;
+
+/**
+ * Creates a reusable, scope-aware proxy rule function.
+ *
+ * @example
+ * const authRule = defineProxy("auth", async (req, ctx) => next())
+ * const scopedAuthRule = authRule({ include: path("/admin/*") })
+ */
+declare function defineProxy<TContext = ProxyContext>(run: ProxyFn<TContext>): DefinedProxy<TContext>;
+declare function defineProxy<TContext = ProxyContext>(name: string, run: ProxyFn<TContext>): DefinedProxy<TContext>;
 /**
- * Compose proxy rules into a single Edge entry (`proxy.ts` / middleware).
+ * Composes independent proxy rules into a single pipeline for Next.js 15 (middleware.ts) and Next.js 16 (proxy.ts).
  *
  * @example
  * export default proxyChain({ debug: true }, [
- *   hostProxy,
- *   demoAuthProxy({
- *     include: [
- *       path("/admin/*"),
- *       { host: "shop.localhost", path: "/checkout/*" },
- *     ],
- *     exclude: { host: "museum.localhost" },
- *   }),
- *   i18nProxy,
+ *   requestIdRule,
+ *   authRule({ include: path("/dashboard/*") }),
+ *   i18nRule,
  * ])
  */
 declare function proxyChain<TContext = ProxyContext>(entries: Entry<TContext>[]): (req: NextRequest, event: NextFetchEvent) => Promise<NextResponse | Response>;
 declare function proxyChain<TContext = ProxyContext>(options: ProxyChainOptions<TContext>, entries: Entry<TContext>[]): (req: NextRequest, event: NextFetchEvent) => Promise<NextResponse | Response>;
 
-export { BaseProxyRule, type ChainConfig, ChainLogger, type DefinedProxy, MergeStrategy, NextResult, type ProxyChainOptions, ProxyContext, type ProxyFn, ProxyPathFilter, type ProxyRule, RequestHeaderPolicy, assertOverrideMechanismSupported, defineProxy, proxyChain, safeInternalError };
+export { type BaseProxyRule, type ChainConfig, type ChainLogger, type CompiledScope, DEFAULT_BLOCKED_REQUEST_HEADERS, type DefinedProxy, type Entry, type EntryWrite, type HostMatcher, type LogLevel, type MergeStrategy, NEXT, type NextOptions, type NextResult, type PathMatcher, type PathOptions, type PipelineOutcome, type ProxyChainOptions, type ProxyContext, type ProxyFn, type ProxyPathFilter, type ProxyResult, type ProxyRule, type RequestHeaderPolicy, type ResolvedOutcome, type RouteScopeInput, type RouteScopeList, RuleTimeoutError, applyMergedToResponse, assertIncludeExcludeNoOverlap, assertOverrideMechanismSupported, compileScopes, cookieItemsFromHeaders, createConsoleLogger, createProxyContext, decodeOverriddenRequestHeaders, defineProxy, finalizeResponse, formatPipelineLine, headersDiffer, headersInitToHeaders, host, isNextResult, isRequestHeaderAllowed, listSetCookie, mergeRequestHeaderOverrides, mergeWrites, next, normalizeHost, parseCookieName, path, pathMatches, proxyChain, resolveRuleResult, responseHeaderItems, ruleLabel, ruleMatches, safeInternalError, toPathRegex, toRule, toStatelessRegExp, withPaths, withRuleTimeout };

package/dist/index.d.ts

@@ -1,31 +1,105 @@
 import { NextRequest, NextFetchEvent, NextResponse } from 'next/server';
-import { ProxyContext, MergeStrategy, ChainLogger, RequestHeaderPolicy, NextResult, ProxyPathFilter, BaseProxyRule } from './core.js';
-export { CompiledScope, DEFAULT_BLOCKED_REQUEST_HEADERS, EntryWrite, HostMatcher, LogLevel, NEXT, NextOptions, PathMatcher, PathOptions, PipelineOutcome, ProxyResult, RouteScopeInput, RouteScopeList, RuleTimeoutError, applyMergedToResponse, assertIncludeExcludeNoOverlap, compileScopes, cookieItemsFromHeaders, createConsoleLogger, createProxyContext, decodeOverriddenRequestHeaders, formatPipelineLine, headersDiffer, host, isNextResult, isRequestHeaderAllowed, listSetCookie, mergeRequestHeaderOverrides, mergeWrites, next, normalizeHost, parseCookieName, path, pathMatches, responseHeaderItems, ruleLabel, ruleMatches, toPathRegex, toRule, toStatelessRegExp, withPaths, withRuleTimeout } from './core.js';
 
 /**
- * A single proxy step.
- *
- * Contract:
- * - `return` / `undefined` — continue with no mutations
- * - `return next({ request?, headers? })` — continue with mutations
- * - `return Response | NextResponse` — if NextResponse.next() or NextResponse.rewrite(), chain continues with mutations; otherwise terminates after merge
- *
- * Third-party middleware (e.g. next-intl) should run **last** and return its
- * Response directly; any terminal Response terminates the chain after merge.
+ * Unique symbol identifying an explicit continue action in the proxy chain pipeline.
+ */
+declare const NEXT: unique symbol;
+/**
+ * Protected request headers that cannot be rewritten unless explicitly permitted by policy.
+ */
+declare const DEFAULT_BLOCKED_REQUEST_HEADERS: readonly string[];
+
+/**
+ * Configuration options for chain continuation.
+ */
+type NextOptions = {
+    /** Request header overrides visible to downstream rules and handlers. */
+    request?: HeadersInit;
+    /** Response headers merged into the final outgoing response. */
+    headers?: HeadersInit;
+};
+/**
+ * Continuation token indicating the pipeline should proceed to subsequent rules.
+ */
+type NextResult = NextOptions & {
+    readonly [NEXT]: true;
+};
+/**
+ * Shared state for an individual request pipeline execution.
+ * Backed by Map to eliminate prototype-pollution risks.
+ */
+type ProxyContext = Map<string, unknown>;
+type ProxyResult<TResponse = NextResponse | Response> = TResponse | NextResult | undefined | void;
+type PathMatcher = RegExp | string;
+type PathOptions = {
+    /** Optional locale prefixes for path matching. */
+    locales?: readonly string[];
+};
+type HostMatcher = string | RegExp | readonly (string | RegExp)[];
+/**
+ * Scoping configuration for rule inclusion or exclusion.
+ */
+type RouteScopeInput = PathMatcher | {
+    host: HostMatcher;
+    path?: PathMatcher | PathMatcher[];
+} | {
+    path: PathMatcher | PathMatcher[];
+    host?: HostMatcher;
+};
+type RouteScopeList = RouteScopeInput | RouteScopeInput[];
+/** Compiled route scope evaluated during request execution. */
+type CompiledScope = {
+    host?: RegExp;
+    path?: RegExp;
+};
+interface BaseProxyRule<TFn> {
+    run: TFn;
+    include?: CompiledScope[];
+    exclude?: CompiledScope[];
+    name?: string;
+}
+type ProxyPathFilter = {
+    include?: RouteScopeList;
+    exclude?: RouteScopeList;
+    name?: string;
+    pathOptions?: PathOptions;
+};
+/**
+ * A single proxy execution function.
  */
 type ProxyFn<TContext = ProxyContext> = (req: NextRequest, ctx: TContext, event: NextFetchEvent) => NextResponse | Response | NextResult | undefined | void | Promise<NextResponse | Response | NextResult | undefined | void>;
 type ProxyRule<TContext = ProxyContext> = BaseProxyRule<ProxyFn<TContext>>;
-type Entry<TContext> = ProxyFn<TContext> | ProxyRule<TContext>;
 type DefinedProxy<TContext = ProxyContext> = ProxyFn<TContext> & ((filter: ProxyPathFilter) => ProxyRule<TContext>);
-/**
- * Define a reusable proxy. Call with a path filter to scope it.
- *
- * @example
- * defineProxy("auth", (req, ctx) => next())
- * demoAuthProxy({ include: path("/admin/*") })
- */
-declare function defineProxy<TContext = ProxyContext>(run: ProxyFn<TContext>): DefinedProxy<TContext>;
-declare function defineProxy<TContext = ProxyContext>(name: string, run: ProxyFn<TContext>): DefinedProxy<TContext>;
+type Entry<TContext = ProxyContext> = ProxyFn<TContext> | ProxyRule<TContext>;
+type MergeStrategy = "last-write-wins" | "first-write-wins" | ((key: string, existing: string, incoming: string) => string | null);
+interface EntryWrite {
+    ruleIndex: number;
+    ruleName: string;
+    items: Map<string, string>;
+}
+type LogLevel = "debug" | "info" | "warn" | "error";
+interface ChainLogger {
+    debug: (metaOrMsg: unknown, maybeMsg?: string) => void;
+    info: (metaOrMsg: unknown, maybeMsg?: string) => void;
+    warn: (metaOrMsg: unknown, maybeMsg?: string) => void;
+    error: (metaOrMsg: unknown, maybeMsg?: string) => void;
+}
+type PipelineOutcome = {
+    kind: "passed";
+    duration: number;
+} | {
+    kind: "next";
+    duration: number;
+    headers: number;
+} | {
+    kind: "stop";
+    duration: number;
+    status: number;
+};
+interface RequestHeaderPolicy {
+    blocked?: readonly string[];
+    allowed?: readonly string[];
+}
 interface ChainConfig<TContext = ProxyContext> {
     createContext: (req: NextRequest, event: NextFetchEvent) => TContext;
     cookieMergeStrategy: MergeStrategy;
@@ -33,33 +107,179 @@ interface ChainConfig<TContext = ProxyContext> {
     onError?: (err: unknown, ruleIndex: number, req: NextRequest, ctx: TContext) => NextResponse | Response | undefined | void | Promise<NextResponse | Response | undefined | void>;
     debug: boolean;
     logger: ChainLogger;
-    /** Per-rule wall-clock limit in ms. `0` disables. */
+    /** Maximum wall-clock execution time per rule in milliseconds. 0 disables timeout. */
     ruleTimeoutMs: number;
     requestHeaderPolicy: RequestHeaderPolicy;
-    /** Throw an error if platform does not support request header overrides. Defaults to false (logs warning). */
+    /** Throw an error on startup if the runtime platform does not support request header overrides. */
     strictOverrideCheck?: boolean;
 }
 type ProxyChainOptions<TContext = ProxyContext> = Partial<ChainConfig<TContext>>;
+
+/**
+ * Creates an isolated per-request context instance.
+ * Backed by Map to eliminate prototype pollution risks.
+ */
+declare function createProxyContext(): ProxyContext;
+
+/**
+ * Strips sticky and global flags (g, y) from RegExp instances.
+ * On Edge runtimes, compiled regex instances can be shared across requests;
+ * sticky and global flags mutate stateful indices, causing non-deterministic matching.
+ */
+declare function toStatelessRegExp(re: RegExp): RegExp;
+/**
+ * Builds a compiled Host matcher RegExp from domain names, wildcards, or regex patterns.
+ */
+declare function host(matcher: HostMatcher): RegExp;
+/**
+ * Compiles a path pattern (glob string, param pattern, or RegExp) into a stateless regular expression.
+ */
+declare function path(pattern: string | RegExp, options?: PathOptions): RegExp;
+declare function toPathRegex(matcher: PathMatcher | PathMatcher[], options?: PathOptions): RegExp;
+/**
+ * Compiles route scoping declarations into normalized regex clauses.
+ */
+declare function compileScopes(input: RouteScopeList | undefined, pathOptions?: PathOptions): CompiledScope[] | undefined;
+declare function toRule<TFn>(entry: TFn | BaseProxyRule<TFn>): BaseProxyRule<TFn>;
+declare function ruleLabel<TFn>(rule: BaseProxyRule<TFn>, index: number): string;
+/**
+ * Decorates a proxy entry with declarative path and host inclusion/exclusion filters.
+ */
+declare function withPaths<TFn>(entry: TFn | BaseProxyRule<TFn>, filter: ProxyPathFilter): BaseProxyRule<TFn>;
+/**
+ * Determines whether a given request matches a rule's scoping constraints.
+ */
+declare function ruleMatches<TFn>(pathname: string, hostname: string | null, rule: BaseProxyRule<TFn>): boolean;
+declare function pathMatches<TFn>(pathname: string, rule: BaseProxyRule<TFn>): boolean;
+/**
+ * Normalizes Host or X-Forwarded-Host header values to lower-case hostname without port.
+ */
+declare function normalizeHost(raw: string | null | undefined): string | null;
+/**
+ * Validates that an identical scope is not declared simultaneously in include and exclude.
+ */
+declare function assertIncludeExcludeNoOverlap(include: CompiledScope[] | undefined, exclude: CompiledScope[] | undefined, label: string): void;
+
+/**
+ * Converts HeadersInit or undefined to a standard Web Headers instance.
+ */
+declare function headersInitToHeaders(init?: HeadersInit): Headers;
+/**
+ * Compares two Headers instances to determine if overrides contain differences.
+ */
+declare function headersDiffer(base: Headers, overrides: Headers): boolean;
+/**
+ * Checks whether a request header is permitted to be mutated under the configured policy.
+ */
+declare function isRequestHeaderAllowed(name: string, policy?: RequestHeaderPolicy): boolean;
+/**
+ * Merges new request header overrides into the target Headers instance, filtering prohibited headers.
+ */
+declare function mergeRequestHeaderOverrides(target: Headers, overrides: Headers, policy?: RequestHeaderPolicy): {
+    applied: number;
+    dropped: string[];
+};
+/**
+ * Extracts cookie name from a raw Set-Cookie directive.
+ */
+declare function parseCookieName(setCookie: string): string;
+/**
+ * Extracts all Set-Cookie directives using standard getSetCookie() when available.
+ */
+declare function listSetCookie(headers: Headers): string[];
+/**
+ * Maps cookie name to Set-Cookie header value from a Headers instance.
+ */
+declare function cookieItemsFromHeaders(headers: Headers): Map<string, string>;
+/**
+ * Filters out Set-Cookie and internal transport headers (x-middleware-*) from response headers.
+ */
+declare function responseHeaderItems(headers: Headers): Map<string, string>;
+/**
+ * Decodes Next.js request header overrides encoded into response headers.
+ */
+declare function decodeOverriddenRequestHeaders(headers: Headers): Headers;
+/**
+ * Deterministically merges writes across rules based on configured strategy.
+ */
+declare function mergeWrites(writes: EntryWrite[], strategy: MergeStrategy, onConflict?: (key: string, winner: string, loser: string) => void): Map<string, string>;
+/**
+ * Applies merged headers and deduplicated cookies onto an outgoing response.
+ */
+declare function applyMergedToResponse(res: Response, headers: Map<string, string>, cookies: Map<string, string>): void;
+
+/**
+ * Creates a continuation action instructing the proxy chain to proceed to subsequent rules.
+ *
+ * @param options - Optional request and response header mutations.
+ * @returns NextResult token indicating pipeline continuation.
+ */
+declare function next(options?: NextOptions): NextResult;
+/**
+ * Type guard verifying whether a returned value is a proxy continuation token.
+ *
+ * @param value - Value to test.
+ * @returns True if value is a NextResult continuation token.
+ */
+declare function isNextResult(value: unknown): value is NextResult;
+
+declare function createConsoleLogger(minLevel?: LogLevel): ChainLogger;
+/**
+ * Formats a single structured log line for an executed proxy rule.
+ */
+declare function formatPipelineLine(input: {
+    method: string;
+    path: string;
+    name: string;
+    traceId?: string;
+    outcome: PipelineOutcome;
+}): string;
+
+declare class RuleTimeoutError extends Error {
+    readonly ruleName: string;
+    readonly timeoutMs: number;
+    constructor(ruleName: string, timeoutMs: number);
+}
+/**
+ * Enforces a strict execution time budget on an asynchronous rule operation.
+ */
+declare function withRuleTimeout<T>(promise: Promise<T>, timeoutMs: number | undefined, ruleName: string): Promise<T>;
+
 declare function safeInternalError(): NextResponse;
-/** Assert once per process at construction time that NextResponse.next() supports request header overrides. */
 declare function assertOverrideMechanismSupported(strict?: boolean): boolean;
+type ResolvedOutcome = {
+    kind: "continue";
+    request?: Headers;
+    responseHeaders: Map<string, string>;
+    cookies: Map<string, string>;
+    rewriteUrl?: string;
+} | {
+    kind: "stop";
+    response: NextResponse | Response;
+};
+declare function resolveRuleResult(res: NextResponse | Response | NextResult | undefined | void, requestHeaderPolicy: RequestHeaderPolicy, logger: ChainLogger, debug: boolean): ResolvedOutcome;
+declare function finalizeResponse(res: NextResponse | Response, headerWrites: EntryWrite[], cookieWrites: EntryWrite[], headerStrategy: MergeStrategy, cookieStrategy: MergeStrategy, logger: ChainLogger, debug: boolean): NextResponse | Response;
+
+/**
+ * Creates a reusable, scope-aware proxy rule function.
+ *
+ * @example
+ * const authRule = defineProxy("auth", async (req, ctx) => next())
+ * const scopedAuthRule = authRule({ include: path("/admin/*") })
+ */
+declare function defineProxy<TContext = ProxyContext>(run: ProxyFn<TContext>): DefinedProxy<TContext>;
+declare function defineProxy<TContext = ProxyContext>(name: string, run: ProxyFn<TContext>): DefinedProxy<TContext>;
 /**
- * Compose proxy rules into a single Edge entry (`proxy.ts` / middleware).
+ * Composes independent proxy rules into a single pipeline for Next.js 15 (middleware.ts) and Next.js 16 (proxy.ts).
  *
  * @example
  * export default proxyChain({ debug: true }, [
- *   hostProxy,
- *   demoAuthProxy({
- *     include: [
- *       path("/admin/*"),
- *       { host: "shop.localhost", path: "/checkout/*" },
- *     ],
- *     exclude: { host: "museum.localhost" },
- *   }),
- *   i18nProxy,
+ *   requestIdRule,
+ *   authRule({ include: path("/dashboard/*") }),
+ *   i18nRule,
  * ])
  */
 declare function proxyChain<TContext = ProxyContext>(entries: Entry<TContext>[]): (req: NextRequest, event: NextFetchEvent) => Promise<NextResponse | Response>;
 declare function proxyChain<TContext = ProxyContext>(options: ProxyChainOptions<TContext>, entries: Entry<TContext>[]): (req: NextRequest, event: NextFetchEvent) => Promise<NextResponse | Response>;
 
-export { BaseProxyRule, type ChainConfig, ChainLogger, type DefinedProxy, MergeStrategy, NextResult, type ProxyChainOptions, ProxyContext, type ProxyFn, ProxyPathFilter, type ProxyRule, RequestHeaderPolicy, assertOverrideMechanismSupported, defineProxy, proxyChain, safeInternalError };
+export { type BaseProxyRule, type ChainConfig, type ChainLogger, type CompiledScope, DEFAULT_BLOCKED_REQUEST_HEADERS, type DefinedProxy, type Entry, type EntryWrite, type HostMatcher, type LogLevel, type MergeStrategy, NEXT, type NextOptions, type NextResult, type PathMatcher, type PathOptions, type PipelineOutcome, type ProxyChainOptions, type ProxyContext, type ProxyFn, type ProxyPathFilter, type ProxyResult, type ProxyRule, type RequestHeaderPolicy, type ResolvedOutcome, type RouteScopeInput, type RouteScopeList, RuleTimeoutError, applyMergedToResponse, assertIncludeExcludeNoOverlap, assertOverrideMechanismSupported, compileScopes, cookieItemsFromHeaders, createConsoleLogger, createProxyContext, decodeOverriddenRequestHeaders, defineProxy, finalizeResponse, formatPipelineLine, headersDiffer, headersInitToHeaders, host, isNextResult, isRequestHeaderAllowed, listSetCookie, mergeRequestHeaderOverrides, mergeWrites, next, normalizeHost, parseCookieName, path, pathMatches, proxyChain, resolveRuleResult, responseHeaderItems, ruleLabel, ruleMatches, safeInternalError, toPathRegex, toRule, toStatelessRegExp, withPaths, withRuleTimeout };