@qzsy/vinext 0.1.7

package/dist/server/html.d.ts

@@ -0,0 +1,28 @@
+//#region src/server/html.d.ts
+/**
+ * HTML-safe JSON serialization for embedding data in <script> tags.
+ *
+ * JSON.stringify does NOT escape characters that are meaningful to the
+ * HTML parser. If a JSON string value contains "</script>", the browser
+ * closes the script tag early — anything after it executes as HTML.
+ * This is a well-known stored XSS vector in SSR frameworks.
+ *
+ * Next.js mitigates this with htmlEscapeJsonString(). We do the same.
+ *
+ * Characters escaped:
+ *   <   → \u003c   (prevents </script> and <!-- breakout)
+ *   >   → \u003e   (prevents --> and other HTML close sequences)
+ *   &   → \u0026   (prevents &lt; entity interpretation in XHTML)
+ *   \u2028 → \\u2028 (line separator — invalid in JS string literals pre-ES2019)
+ *   \u2029 → \\u2029 (paragraph separator — same)
+ *
+ * The result is valid JSON that is also safe to embed in any HTML context
+ * without additional escaping.
+ */
+declare function safeJsonStringify(data: unknown): string;
+declare function escapeHtmlAttr(value: string): string;
+declare function htmlTokenListContains(value: string | null, token: string): boolean;
+declare function createNonceAttribute(nonce?: string): string;
+declare function createInlineScriptTag(content: string, nonce?: string): string;
+//#endregion
+export { createInlineScriptTag, createNonceAttribute, escapeHtmlAttr, htmlTokenListContains, safeJsonStringify };

package/dist/server/html.js

@@ -0,0 +1,41 @@
+//#region src/server/html.ts
+/**
+* HTML-safe JSON serialization for embedding data in <script> tags.
+*
+* JSON.stringify does NOT escape characters that are meaningful to the
+* HTML parser. If a JSON string value contains "<\/script>", the browser
+* closes the script tag early — anything after it executes as HTML.
+* This is a well-known stored XSS vector in SSR frameworks.
+*
+* Next.js mitigates this with htmlEscapeJsonString(). We do the same.
+*
+* Characters escaped:
+*   <   → \u003c   (prevents <\/script> and <!-- breakout)
+*   >   → \u003e   (prevents --> and other HTML close sequences)
+*   &   → \u0026   (prevents &lt; entity interpretation in XHTML)
+*   \u2028 → \\u2028 (line separator — invalid in JS string literals pre-ES2019)
+*   \u2029 → \\u2029 (paragraph separator — same)
+*
+* The result is valid JSON that is also safe to embed in any HTML context
+* without additional escaping.
+*/
+function safeJsonStringify(data) {
+	return JSON.stringify(data).replace(/</g, "\\u003c").replace(/>/g, "\\u003e").replace(/&/g, "\\u0026").replace(/\u2028/g, "\\u2028").replace(/\u2029/g, "\\u2029");
+}
+function escapeHtmlAttr(value) {
+	return value.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+const HTML_SPACE_RE = /[\t\n\f\r ]+/;
+function htmlTokenListContains(value, token) {
+	if (value === null) return false;
+	return value.split(HTML_SPACE_RE).some((part) => part.length > 0 && part.toLowerCase() === token.toLowerCase());
+}
+function createNonceAttribute(nonce) {
+	if (!nonce) return "";
+	return ` nonce="${escapeHtmlAttr(nonce)}"`;
+}
+function createInlineScriptTag(content, nonce) {
+	return `<script${createNonceAttribute(nonce)}>${content}<\/script>`;
+}
+//#endregion
+export { createInlineScriptTag, createNonceAttribute, escapeHtmlAttr, htmlTokenListContains, safeJsonStringify };

package/dist/server/http-error-responses.d.ts

@@ -0,0 +1,91 @@
+//#region src/server/http-error-responses.d.ts
+/**
+ * Shared HTTP error response builders.
+ *
+ * Centralizes the canonical `new Response("...", { status: 4xx | 5xx })` patterns
+ * that previously were scattered across server modules. Each helper standardizes
+ * the canonical body for its status; the optional `headers` argument lets callers
+ * merge middleware/middleware-context headers without re-implementing the
+ * `new Response(...)` boilerplate.
+ *
+ * Sites with route-specific bodies (e.g. `"404 - API route not found"`,
+ * `"Image not found"`, generated worker templates) intentionally remain inline
+ * because their bodies are either tested-against fixtures or run inside template
+ * strings that have no access to runtime imports.
+ *
+ * Follow-up to #1058 / #1071 / #1078, which extracted the first batch of these
+ * helpers (action/page error responses, `forbiddenResponse`, `payloadTooLargeResponse`).
+ */
+type ErrorResponseInit = {
+  headers?: HeadersInit;
+};
+/**
+ * Build a 400 Bad Request plain-text response.
+ *
+ * Used for malformed percent-encoding, invalid HTTP methods (where Next.js
+ * returns 400), and other request-shape validation failures.
+ */
+declare function badRequestResponse(init?: ErrorResponseInit): Response;
+/**
+ * Build a 403 Forbidden plain-text response.
+ *
+ * Used by CSRF origin validation and dev-server origin checks.
+ */
+declare function forbiddenResponse(): Response;
+/**
+ * Build a 404 Not Found plain-text response.
+ *
+ * The body matches Next.js's plain-text 404 response exactly. Next.js writes
+ * `res.end('This page could not be found')` (no trailing period) for the
+ * fallback 404 path; see in `.nextjs-ref`:
+ *   - packages/next/src/server/route-modules/pages/pages-handler.ts L121, L535
+ *   - packages/next/src/build/templates/app-route.ts L170, L349
+ *   - packages/next/src/build/templates/app-page.ts L701, L1043
+ * (The React-rendered not-found component in `packages/next/src/client/components/builtin/not-found.tsx`
+ * uses the same text with a trailing period — that variant is rendered as HTML,
+ * not returned as the plain-text body.)
+ *
+ * The `headers` option lets call sites merge middleware response headers into
+ * the 404, matching the pattern used by `app-rsc-handler` after a route match
+ * fails but middleware has already contributed headers.
+ */
+declare function notFoundResponse(init?: ErrorResponseInit): Response;
+/**
+ * Build a 404 plain-text response for invalid `_next/static/*` paths.
+ *
+ * Next.js short-circuits invalid `_next/static/*` requests with a plain-text
+ * `"Not Found"` body (NOT the rendered HTML 404 page) — saves bandwidth on
+ * what is almost certainly a misbehaving client requesting a stale chunk.
+ *
+ * Body and content-type match Next.js exactly:
+ *   res.statusCode = 404
+ *   res.setHeader('Content-Type', 'text/plain; charset=utf-8')
+ *   res.end('Not Found')
+ *
+ * @see packages/next/src/server/lib/router-server.ts in `.nextjs-ref`
+ */
+declare function notFoundStaticAssetResponse(): Response;
+/**
+ * Build a 405 Method Not Allowed plain-text response with the `Allow` header set.
+ *
+ * `allowedMethods` is rendered as the comma-separated `Allow` header value.
+ * Existing headers (e.g. middleware response headers) can be merged via `init.headers`;
+ * the `Allow` header takes precedence and overwrites any colliding entry.
+ */
+declare function methodNotAllowedResponse(allowedMethods: string, init?: ErrorResponseInit): Response;
+/**
+ * Build a 413 Payload Too Large plain-text response.
+ *
+ * Used by server action body-size enforcement.
+ */
+declare function payloadTooLargeResponse(): Response;
+/**
+ * Build a 500 Internal Server Error plain-text response.
+ *
+ * The `message` argument lets dev-mode handlers surface failure details while
+ * production paths fall back to the canonical body. Pass `undefined` (or omit)
+ * to use the canonical "Internal Server Error" body.
+ */
+declare function internalServerErrorResponse(message?: string, init?: ErrorResponseInit): Response;
+//#endregion
+export { badRequestResponse, forbiddenResponse, internalServerErrorResponse, methodNotAllowedResponse, notFoundResponse, notFoundStaticAssetResponse, payloadTooLargeResponse };

package/dist/server/http-error-responses.js

@@ -0,0 +1,105 @@
+//#region src/server/http-error-responses.ts
+/**
+* Build a 400 Bad Request plain-text response.
+*
+* Used for malformed percent-encoding, invalid HTTP methods (where Next.js
+* returns 400), and other request-shape validation failures.
+*/
+function badRequestResponse(init) {
+	return new Response("Bad Request", {
+		status: 400,
+		headers: init?.headers
+	});
+}
+/**
+* Build a 403 Forbidden plain-text response.
+*
+* Used by CSRF origin validation and dev-server origin checks.
+*/
+function forbiddenResponse() {
+	return new Response("Forbidden", {
+		status: 403,
+		headers: { "Content-Type": "text/plain" }
+	});
+}
+/**
+* Build a 404 Not Found plain-text response.
+*
+* The body matches Next.js's plain-text 404 response exactly. Next.js writes
+* `res.end('This page could not be found')` (no trailing period) for the
+* fallback 404 path; see in `.nextjs-ref`:
+*   - packages/next/src/server/route-modules/pages/pages-handler.ts L121, L535
+*   - packages/next/src/build/templates/app-route.ts L170, L349
+*   - packages/next/src/build/templates/app-page.ts L701, L1043
+* (The React-rendered not-found component in `packages/next/src/client/components/builtin/not-found.tsx`
+* uses the same text with a trailing period — that variant is rendered as HTML,
+* not returned as the plain-text body.)
+*
+* The `headers` option lets call sites merge middleware response headers into
+* the 404, matching the pattern used by `app-rsc-handler` after a route match
+* fails but middleware has already contributed headers.
+*/
+function notFoundResponse(init) {
+	return new Response("This page could not be found", {
+		status: 404,
+		headers: init?.headers
+	});
+}
+/**
+* Build a 404 plain-text response for invalid `_next/static/*` paths.
+*
+* Next.js short-circuits invalid `_next/static/*` requests with a plain-text
+* `"Not Found"` body (NOT the rendered HTML 404 page) — saves bandwidth on
+* what is almost certainly a misbehaving client requesting a stale chunk.
+*
+* Body and content-type match Next.js exactly:
+*   res.statusCode = 404
+*   res.setHeader('Content-Type', 'text/plain; charset=utf-8')
+*   res.end('Not Found')
+*
+* @see packages/next/src/server/lib/router-server.ts in `.nextjs-ref`
+*/
+function notFoundStaticAssetResponse() {
+	return new Response("Not Found", {
+		status: 404,
+		headers: { "Content-Type": "text/plain; charset=utf-8" }
+	});
+}
+/**
+* Build a 405 Method Not Allowed plain-text response with the `Allow` header set.
+*
+* `allowedMethods` is rendered as the comma-separated `Allow` header value.
+* Existing headers (e.g. middleware response headers) can be merged via `init.headers`;
+* the `Allow` header takes precedence and overwrites any colliding entry.
+*/
+function methodNotAllowedResponse(allowedMethods, init) {
+	const headers = new Headers(init?.headers);
+	headers.set("Allow", allowedMethods);
+	return new Response("Method Not Allowed", {
+		status: 405,
+		headers
+	});
+}
+/**
+* Build a 413 Payload Too Large plain-text response.
+*
+* Used by server action body-size enforcement.
+*/
+function payloadTooLargeResponse() {
+	return new Response("Payload Too Large", { status: 413 });
+}
+/**
+* Build a 500 Internal Server Error plain-text response.
+*
+* The `message` argument lets dev-mode handlers surface failure details while
+* production paths fall back to the canonical body. Pass `undefined` (or omit)
+* to use the canonical "Internal Server Error" body.
+*/
+function internalServerErrorResponse(message, init) {
+	return new Response(message ?? "Internal Server Error", {
+		status: 500,
+		headers: init?.headers
+	});
+}
+//#endregion
+export { badRequestResponse, forbiddenResponse, internalServerErrorResponse, methodNotAllowedResponse, notFoundResponse, notFoundStaticAssetResponse, payloadTooLargeResponse };

package/dist/server/hybrid-route-priority.d.ts

@@ -0,0 +1,22 @@
+//#region src/server/hybrid-route-priority.d.ts
+type HybridRoutePriorityRoute = {
+  isDynamic: boolean;
+  pattern: string;
+  sourcePath?: string | null;
+};
+declare function validateHybridRouteConflicts(pagesRoutes: readonly HybridRoutePriorityRoute[], appRoutes: readonly HybridRoutePriorityRoute[]): void;
+/**
+ * Return whether a matched Pages Router route should own the request instead
+ * of a matched App Router route.
+ *
+ * Next.js registers Pages providers before App providers, then sorts all
+ * dynamic route pathnames together in DefaultRouteMatcherManager. Vinext keeps
+ * separate route tries for each router, so the hybrid boundary needs to apply
+ * that same cross-router ordering after both routers have produced their best
+ * local match. The decision itself lives in
+ * `routing/utils.ts#compareHybridRoutePatterns` so the server and client
+ * always reach the same answer.
+ */
+declare function pagesRouteHasPriorityOverAppRoute(pagesRoute: HybridRoutePriorityRoute, appRoute: HybridRoutePriorityRoute | null): boolean;
+//#endregion
+export { HybridRoutePriorityRoute, pagesRouteHasPriorityOverAppRoute, validateHybridRouteConflicts };

package/dist/server/hybrid-route-priority.js

@@ -0,0 +1,33 @@
+import { compareHybridRoutePatterns } from "../routing/utils.js";
+import { validateRoutePatterns } from "../routing/route-validation.js";
+//#region src/server/hybrid-route-priority.ts
+function validateHybridRouteConflicts(pagesRoutes, appRoutes) {
+	const pagesByPattern = new Map(pagesRoutes.map((route) => [route.pattern, route]));
+	const conflicts = appRoutes.flatMap((appRoute) => {
+		const pagesRoute = pagesByPattern.get(appRoute.pattern);
+		return pagesRoute === void 0 ? [] : [[pagesRoute, appRoute]];
+	});
+	if (conflicts.length > 0) {
+		const message = `Conflicting app and page file${conflicts.length === 1 ? " was" : "s were"} found, please remove the conflicting files to continue:`;
+		throw new Error(`${message}\n${conflicts.map(([pagesRoute, appRoute]) => `  "${pagesRoute.sourcePath ?? pagesRoute.pattern}" - "${appRoute.sourcePath ?? appRoute.pattern}"`).join("\n")}`);
+	}
+	validateRoutePatterns([...pagesRoutes.map((route) => route.pattern), ...appRoutes.map((route) => route.pattern)]);
+}
+/**
+* Return whether a matched Pages Router route should own the request instead
+* of a matched App Router route.
+*
+* Next.js registers Pages providers before App providers, then sorts all
+* dynamic route pathnames together in DefaultRouteMatcherManager. Vinext keeps
+* separate route tries for each router, so the hybrid boundary needs to apply
+* that same cross-router ordering after both routers have produced their best
+* local match. The decision itself lives in
+* `routing/utils.ts#compareHybridRoutePatterns` so the server and client
+* always reach the same answer.
+*/
+function pagesRouteHasPriorityOverAppRoute(pagesRoute, appRoute) {
+	if (appRoute === null) return true;
+	return compareHybridRoutePatterns(pagesRoute.pattern, pagesRoute.isDynamic, appRoute.pattern, appRoute.isDynamic) === "pages";
+}
+//#endregion
+export { pagesRouteHasPriorityOverAppRoute, validateHybridRouteConflicts };

package/dist/server/image-optimization.d.ts

@@ -0,0 +1,130 @@
+//#region src/server/image-optimization.d.ts
+/**
+ * Image optimization request handler.
+ *
+ * Handles `/_next/image?url=...&w=...&q=...` requests. In production
+ * on Cloudflare Workers, uses the Images binding (`env.IMAGES`) to
+ * resize and transcode on the fly. On other runtimes (Node.js dev/prod
+ * server), serves the original file as a passthrough with appropriate
+ * Cache-Control headers.
+ *
+ * Format negotiation: inspects the `Accept` header and serves AVIF, WebP,
+ * or JPEG depending on client support.
+ *
+ * Security: All image responses include Content-Security-Policy and
+ * X-Content-Type-Options headers to prevent XSS via SVG or Content-Type
+ * spoofing. SVG content is blocked by default (following Next.js behavior).
+ * When `dangerouslyAllowSVG` is enabled in next.config.js, SVGs are served
+ * as-is (no transformation) with security headers applied.
+ */
+/** The pathname that triggers image optimization (matches Next.js). */
+declare const IMAGE_OPTIMIZATION_PATH = "/_next/image";
+/**
+ * Vinext-prefixed alias for the image optimization endpoint. Accepted
+ * alongside IMAGE_OPTIMIZATION_PATH so apps that wire image URLs to the
+ * vinext-prefixed path continue to work; emit IMAGE_OPTIMIZATION_PATH
+ * for any newly generated URLs.
+ */
+declare const VINEXT_IMAGE_OPTIMIZATION_PATH = "/_vinext/image";
+/** Returns true when `pathname` is either supported image optimization endpoint. */
+declare function isImageOptimizationPath(pathname: string): boolean;
+/**
+ * Image security configuration from next.config.js `images` section.
+ * Controls SVG handling and security headers for the image endpoint.
+ */
+type ImageConfig = {
+  /** Allowed device widths. Defaults to Next.js device sizes. */deviceSizes?: number[]; /** Allowed fixed-image widths. Defaults to Next.js image sizes. */
+  imageSizes?: number[];
+  /**
+   * Allowed output qualities. When unset, any quality from 1-100 is permitted
+   * (matches Next.js: an unset `images.qualities` is not restricted to a single
+   * value). When set, only the listed qualities are accepted.
+   */
+  qualities?: number[]; /** Allow SVG through the image optimization endpoint. Default: false. */
+  dangerouslyAllowSVG?: boolean;
+  /**
+   * Allow image optimization for hostnames that resolve to private IP addresses.
+   * Default: false.
+   *
+   * Note: This field is currently reserved for future server-side remote-image
+   * fetching. vinext's image optimization endpoint only serves local files, so
+   * there is no active server-side SSRF vector — the flag is consumed client-side
+   * via the image shim instead.
+   */
+  dangerouslyAllowLocalIP?: boolean; /** Content-Disposition header value. Default: "inline". */
+  contentDispositionType?: "inline" | "attachment"; /** Content-Security-Policy header value. Default: "script-src 'none'; frame-src 'none'; sandbox;" */
+  contentSecurityPolicy?: string;
+};
+/**
+ * Next.js default device sizes and image sizes.
+ * These are the allowed widths for image optimization when no custom
+ * config is provided. Matches Next.js defaults exactly.
+ */
+declare const DEFAULT_DEVICE_SIZES: number[];
+declare const DEFAULT_IMAGE_SIZES: number[];
+type ParseImageParamsOptions = {
+  isDev?: boolean;
+};
+/**
+ * Pick the allowed width numerically closest to the requested value.
+ * On a tie, prefer the larger width so the served image is not undersized.
+ */
+declare function snapToNearestAllowedWidth(requestedWidth: number, allowedWidths: number[]): number;
+declare function resolveDevImageRedirect(requestUrl: URL, allowedWidths?: number[], allowedQualities?: number[], options?: ParseImageParamsOptions): string | null;
+/**
+ * Parse and validate image optimization query parameters.
+ * Returns null if the request is malformed.
+ *
+ * Ported from Next.js:
+ * test/integration/image-optimizer/test/index.test.ts
+ * https://github.com/vercel/next.js/blob/canary/test/integration/image-optimizer/test/index.test.ts
+ */
+declare function parseImageParams(url: URL, allowedWidths?: number[], allowedQualities?: number[], options?: ParseImageParamsOptions): {
+  imageUrl: string;
+  width: number;
+  quality: number;
+} | null;
+/**
+ * Negotiate the best output format based on the Accept header.
+ * Returns an IANA media type.
+ */
+declare function negotiateImageFormat(acceptHeader: string | null): string;
+/**
+ * Standard Cache-Control header for optimized images.
+ * Optimized images are immutable because the URL encodes the transform params.
+ */
+declare const IMAGE_CACHE_CONTROL = "public, max-age=31536000, immutable";
+/**
+ * Content-Security-Policy for image optimization responses.
+ * Blocks script execution and framing to prevent XSS via SVG or other
+ * active content that might be served through the image endpoint.
+ * Matches Next.js default: script-src 'none'; frame-src 'none'; sandbox;
+ */
+declare const IMAGE_CONTENT_SECURITY_POLICY = "script-src 'none'; frame-src 'none'; sandbox;";
+/**
+ * Check if a Content-Type header value is a safe image type.
+ * Returns false for SVG (unless dangerouslyAllowSVG is true), HTML, or any non-image type.
+ */
+declare function isSafeImageContentType(contentType: string | null, dangerouslyAllowSVG?: boolean): boolean;
+/**
+ * Handlers for image optimization I/O operations.
+ * Workers provide these callbacks to adapt their specific bindings.
+ */
+type ImageHandlers = {
+  /** Fetch the source image from storage (e.g., Cloudflare ASSETS binding). */fetchAsset: (path: string, request: Request) => Promise<Response>; /** Optional: Transform the image (resize, format, quality). */
+  transformImage?: (body: ReadableStream, options: {
+    width: number;
+    format: string;
+    quality: number;
+  }) => Promise<Response>;
+};
+/**
+ * Handle image optimization requests.
+ *
+ * Parses and validates the request, fetches the source image via the provided
+ * handlers, optionally transforms it, and returns the response with appropriate
+ * cache headers.
+ */
+declare function handleImageOptimization(request: Request, handlers: ImageHandlers, allowedWidths?: number[], imageConfig?: ImageConfig): Promise<Response>;
+//#endregion
+export { DEFAULT_DEVICE_SIZES, DEFAULT_IMAGE_SIZES, IMAGE_CACHE_CONTROL, IMAGE_CONTENT_SECURITY_POLICY, IMAGE_OPTIMIZATION_PATH, ImageConfig, ImageHandlers, ParseImageParamsOptions, VINEXT_IMAGE_OPTIMIZATION_PATH, handleImageOptimization, isImageOptimizationPath, isSafeImageContentType, negotiateImageFormat, parseImageParams, resolveDevImageRedirect, snapToNearestAllowedWidth };