tina4-nodejs 3.13.97 → 3.13.99

package/packages/core/src/request.ts

@@ -1,4 +1,6 @@
 import type { IncomingMessage, IncomingHttpHeaders } from "node:http";
+import { mkdirSync, realpathSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
 import type { Tina4Request, UploadedFile } from "./types.js";
 import { resolveClientIp } from "./trustedProxy.js";
 
@@ -32,8 +34,19 @@ export function makeCaseInsensitiveHeaders(
   }) as IncomingHttpHeaders;
 }
 
+/** Strips `readonly` so construction code can write once; callers outside
+ * this function still see the real (readonly) `Tina4Request` shape
+ * (REQ-IMMUTABILITY-DIVERGE, 3.13.99). */
+type Writable<T> = { -readonly [K in keyof T]: T[K] };
+
 export function createRequest(req: IncomingMessage): Tina4Request {
   const tReq = req as Tina4Request;
+  // Construction-only mutable view of the same object — the core wire-derived
+  // fields (path/queryString/url/ip/remoteIp/cookies/contentType/query) are
+  // `readonly` on Tina4Request itself; this alias is how THIS function is
+  // still allowed to set them exactly once, the same way PHP's constructor
+  // writes its own `readonly` properties.
+  const w = tReq as Writable<Tina4Request>;
   // Wrap `req.headers` so mixed-case lookups work — Node's underlying object
   // is already lower-cased, this just lets readers use any casing they like.
   (tReq as unknown as { headers: IncomingHttpHeaders }).headers =
@@ -80,17 +93,17 @@ export function createRequest(req: IncomingMessage): Tina4Request {
   }
 
   tReq.params = {};
-  tReq.query = query;
+  w.query = query;
   // Path, query string, and full URL — same shape across all four frameworks.
   // `path` is the URL path only; `queryString` is the raw query without "?".
   // `url` is overridden from Node's IncomingMessage.url (path+query) to the
   // full absolute URL — parity with PHP/Python/Ruby.
-  tReq.path = path;
-  tReq.queryString = queryString;
-  tReq.url = fullUrl;
+  w.path = path;
+  w.queryString = queryString;
+  w.url = fullUrl;
   tReq.body = undefined;
   tReq.files = {};
-  tReq.contentType = (req.headers["content-type"] ?? "") as string;
+  w.contentType = (req.headers["content-type"] ?? "") as string;
 
   // Parse cookies from Cookie header
   const cookieHeader = (req.headers.cookie ?? "") as string;
@@ -101,13 +114,13 @@ export function createRequest(req: IncomingMessage): Tina4Request {
       if (k) cookies[k.trim()] = v.join("=").trim();
     }
   }
-  tReq.cookies = cookies;
+  w.cookies = cookies;
 
   // Raw socket peer — NEVER honours a forwarding header, so it can be trusted
   // for security decisions. Resolved BEFORE .ip: the peer decides whether the
   // forwarding headers may be believed at all (TINA4_TRUSTED_PROXIES, ADR-0019).
-  tReq.remoteIp = req.socket?.remoteAddress ?? "";
-  tReq.ip = resolveClientIp(req.headers, tReq.remoteIp) || "127.0.0.1";
+  w.remoteIp = req.socket?.remoteAddress ?? "";
+  w.ip = resolveClientIp(req.headers, tReq.remoteIp) || "127.0.0.1";
 
   // Add convenience methods
   tReq.header = function (name: string): string | undefined {
@@ -318,6 +331,42 @@ export function parseMultipart(
   return { fields, files };
 }
 
+/**
+ * Persist an uploaded file's content inside `targetDir` under a SAFE name.
+ *
+ * The client-supplied filename is untrusted. Directory components are stripped
+ * (so `../../evil` or `/etc/passwd` becomes `evil` / `passwd`), a NUL byte or an
+ * unusable name (`''`/`.`/`..`) is refused, and the resolved path is confined to
+ * `targetDir` (realpath containment) so an upload can never write outside it.
+ *
+ * @param file an uploaded-file descriptor (`req.files[name]`) carrying `content`.
+ * @param targetDir the directory to write into (created if missing).
+ * @param filename an explicit name to use instead of the client filename.
+ * @returns the absolute path written.
+ * @throws when the derived name is unsafe or would escape `targetDir`.
+ */
+export function saveUpload(file: UploadedFile, targetDir: string, filename?: string): string {
+  const raw = String(filename ?? file.filename ?? "");
+  if (raw.includes("\0")) throw new Error("upload filename contains a null byte");
+  // Reduce to a single path segment, handling BOTH separators so a Windows
+  // "..\\..\\evil" cannot smuggle a directory part past a POSIX basename.
+  const base = raw.replace(/\\/g, "/").split("/").pop() ?? "";
+  if (base === "" || base === "." || base === "..") {
+    throw new Error(`upload filename is not a usable name: ${JSON.stringify(raw)}`);
+  }
+  mkdirSync(targetDir, { recursive: true });
+  const dest = join(targetDir, base);
+  // Defence in depth: the resolved parent of the destination must be exactly
+  // the resolved target dir (guards a pre-existing symlink at target/base).
+  const realDir = realpathSync(targetDir);
+  const realParent = realpathSync(dirname(dest));
+  if (realParent !== realDir) {
+    throw new Error(`refusing to write outside ${targetDir}: ${JSON.stringify(raw)}`);
+  }
+  writeFileSync(dest, file.content);
+  return dest;
+}
+
 function bufferIndexOf(haystack: Buffer, needle: Buffer, offset: number): number {
   for (let i = offset; i <= haystack.length - needle.length; i++) {
     let found = true;

package/packages/core/src/response.ts

@@ -504,3 +504,70 @@ export function createResponse(res: ServerResponse): Tina4Response {
 export function errorResponse(code: string, message: string, status: number = 400): Record<string, unknown> {
   return { error: true, code, message, status };
 }
+
+/**
+ * Content negotiation for an error response (feature 42, ERR-DEC-02): does an
+ * Accept header prefer application/json over text/html?
+ *
+ * `Accept: application/json` (an API client) prefers JSON; a browser Accept
+ * (`text/html`, `*\/*`, or no header at all) prefers HTML. A mixed Accept
+ * header - a real browser's
+ * `text/html,application/xhtml+xml,application/xml;q=0.9,*\/*;q=0.8` - is
+ * resolved by q-value: whichever of the two media types this function cares
+ * about is weighted higher wins; a tie or neither present defaults to HTML,
+ * the historical/back-compatible behaviour for an unspecified client. This is
+ * the ONE shared decision reused by the 403/404/500 error paths (server.ts's
+ * serveNotFound/renderDispatchError, middleware.ts's interpretHookResult), so
+ * a JSON API client sees the SAME negotiated shape everywhere
+ * (ERR-403-SPLIT) - ported with the same algorithm to Python/PHP/Ruby.
+ */
+export function acceptPrefersJson(accept: string | undefined | null): boolean {
+  if (!accept) return false;
+
+  let bestJson = -1;
+  let bestHtml = -1;
+  for (const part of accept.split(",")) {
+    const segments = part.trim().split(";");
+    const media = (segments[0] ?? "").trim().toLowerCase();
+    let q = 1;
+    for (const rawParam of segments.slice(1)) {
+      const param = rawParam.trim();
+      if (param.startsWith("q=")) {
+        const parsed = Number(param.slice(2));
+        if (!Number.isNaN(parsed)) q = parsed;
+      }
+    }
+    if (media === "application/json") {
+      bestJson = Math.max(bestJson, q);
+    } else if (media === "text/html" || media === "*/*" || media === "application/xhtml+xml") {
+      bestHtml = Math.max(bestHtml, q);
+    }
+  }
+
+  if (bestJson < 0) return false;
+  if (bestHtml < 0) return true;
+  return bestJson > bestHtml;
+}
+
+/** True when the request's Accept header prefers JSON - see acceptPrefersJson(). */
+export function wantsJson(req: { headers?: Record<string, string | string[] | undefined> }): boolean {
+  const accept = req?.headers?.["accept"];
+  return acceptPrefersJson(Array.isArray(accept) ? accept[0] : accept);
+}
+
+const ERROR_CODE_NAMES: Record<number, string> = {
+  403: "FORBIDDEN", 404: "NOT_FOUND", 405: "METHOD_NOT_ALLOWED", 500: "INTERNAL_SERVER_ERROR",
+};
+
+/**
+ * The ONE JSON error envelope for a negotiated 403/404/500 (ERR-DEC-02).
+ *
+ * Reuses errorResponse() (error: true, code, message, status) already shared
+ * by app-level response.error() calls, plus request_id for correlation
+ * (feature 43, ERR-404-REQUESTID) - the SAME shape Python/PHP/Ruby build.
+ */
+export function negotiatedErrorBody(code: number, message: string, requestId: string): Record<string, unknown> {
+  const body = errorResponse(ERROR_CODE_NAMES[code] ?? `HTTP_${code}`, message, code);
+  body.request_id = requestId;
+  return body;
+}

package/packages/core/src/router.ts

@@ -39,6 +39,26 @@ function coerceParam(raw: string, type: string | undefined): string | number {
   }
 }
 
+/**
+ * Join a route-group prefix with a route's own path.
+ *
+ * Feature 32 (RG-DEC-01): ports PHP's normalization grammar verbatim
+ * (`Tina4/Router.php` `addRoute` — the reference) so Node converges with
+ * PHP/Python/Ruby instead of `RouteGroup`'s old bare concatenation. One
+ * separator between prefix and path, a single leading slash, no trailing
+ * slash, and any run of slashes collapsed to one — so `group("/api")` +
+ * `get("users")`, `get("/users")`, and `group("/api/")` + `get("/users")`
+ * all resolve to the SAME `/api/users`. Before this fix, `this.prefix +
+ * path` bare-concatenated with NO normalization at all — the worst of the
+ * four, since Node's `RouteGroup` prefix isn't even trailing-slash-trimmed
+ * on construction (unlike Python's `rstrip`/Ruby's `chomp`).
+ */
+function joinGroupPath(prefix: string, path: string): string {
+  const full = `${prefix}/${path.replace(/^\/+/, "")}`;
+  const trimmed = `/${full.replace(/^\/+|\/+$/g, "")}`;
+  return trimmed.replace(/\/+/g, "/");
+}
+
 interface MatchResult {
   handler: RouteHandler;
   params: Record<string, string | number>;
@@ -676,7 +696,15 @@ export class Router {
           paramTypes.push("string");
           return "(.+)";
         }
-        return segment;
+        // Literal segment -- escape every regex metacharacter so it matches
+        // itself only (real-bug pre-merge, 3.13.99). Before this, a literal
+        // segment was interpolated into the pattern string UNESCAPED: e.g.
+        // registering `/blocked-xss(1)` compiled `(1)` as a capture group,
+        // so `new RegExp('^/blocked-xss(1)$')` actually required the URL
+        // WITHOUT the parens -- the exact literal path it was registered
+        // for 404'd. Mirrors Python's re.escape / Ruby's Regexp.escape /
+        // PHP's preg_quote, all already correct here.
+        return segment.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
       })
       .join("/");
 
@@ -708,7 +736,7 @@ export class RouteGroup {
   get(path: string, handler: RouteHandler, middlewares?: MiddlewareSpec[], meta?: RouteMeta): RouteRef {
     return this.router.addRoute({
       method: "GET",
-      pattern: this.prefix + path,
+      pattern: joinGroupPath(this.prefix, path),
       handler,
       middlewares: this.mergeMiddlewares(middlewares),
       meta,
@@ -718,7 +746,7 @@ export class RouteGroup {
   post(path: string, handler: RouteHandler, middlewares?: MiddlewareSpec[], meta?: RouteMeta): RouteRef {
     return this.router.addRoute({
       method: "POST",
-      pattern: this.prefix + path,
+      pattern: joinGroupPath(this.prefix, path),
       handler,
       middlewares: this.mergeMiddlewares(middlewares),
       meta,
@@ -728,7 +756,7 @@ export class RouteGroup {
   put(path: string, handler: RouteHandler, middlewares?: MiddlewareSpec[], meta?: RouteMeta): RouteRef {
     return this.router.addRoute({
       method: "PUT",
-      pattern: this.prefix + path,
+      pattern: joinGroupPath(this.prefix, path),
       handler,
       middlewares: this.mergeMiddlewares(middlewares),
       meta,
@@ -738,7 +766,7 @@ export class RouteGroup {
   patch(path: string, handler: RouteHandler, middlewares?: MiddlewareSpec[], meta?: RouteMeta): RouteRef {
     return this.router.addRoute({
       method: "PATCH",
-      pattern: this.prefix + path,
+      pattern: joinGroupPath(this.prefix, path),
       handler,
       middlewares: this.mergeMiddlewares(middlewares),
       meta,
@@ -748,7 +776,7 @@ export class RouteGroup {
   delete(path: string, handler: RouteHandler, middlewares?: MiddlewareSpec[], meta?: RouteMeta): RouteRef {
     return this.router.addRoute({
       method: "DELETE",
-      pattern: this.prefix + path,
+      pattern: joinGroupPath(this.prefix, path),
       handler,
       middlewares: this.mergeMiddlewares(middlewares),
       meta,
@@ -760,7 +788,7 @@ export class RouteGroup {
     for (const method of ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS", "HEAD"]) {
       lastRef = this.router.addRoute({
         method,
-        pattern: this.prefix + path,
+        pattern: joinGroupPath(this.prefix, path),
         handler,
         middlewares: this.mergeMiddlewares(middlewares),
         meta,