@thi.ng/server 0.9.1 → 0.10.1

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2025-04-01T21:42:04Z
+- **Last updated**: 2025-04-30T12:52:32Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -11,6 +11,15 @@ See [Conventional Commits](https://conventionalcommits.org/) for commit guidelin
 **Note:** Unlisted _patch_ versions only involve non-code or otherwise excluded changes
 and/or version bumps of transitive dependencies.
 
+## [0.10.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/server@0.10.0) (2025-04-16)
+
+#### 🚀 Features
+
+- add `#` in URL safety check, update `RequestCtx` ([f0a7025](https://github.com/thi-ng/umbrella/commit/f0a7025))
+  - respond with HTTP 400 if request URL contains `#`
+    - this stops maliciously contructed requests via HTTP `request-target`
+  - add docs
+
 ## [0.9.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/server@0.9.0) (2025-03-22)
 
 #### 🚀 Features

package/README.md

@@ -7,7 +7,7 @@
 [![Mastodon Follow](https://img.shields.io/mastodon/follow/109331703950160316?domain=https%3A%2F%2Fmastodon.thi.ng&style=social)](https://mastodon.thi.ng/@toxi)
 
 > [!NOTE]
-> This is one of 205 standalone projects, maintained as part
+> This is one of 206 standalone projects, maintained as part
 > of the [@thi.ng/umbrella](https://github.com/thi-ng/umbrella/) monorepo
 > and anti-framework.
 >
@@ -164,7 +164,7 @@ For Node.js REPL:
 const ser = await import("@thi.ng/server");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 6.25 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 6.27 KB
 
 ## Dependencies
 

package/api.d.ts

@@ -85,17 +85,69 @@ export interface CompiledServerRoute<CTX extends RequestCtx = RequestCtx> extend
     handlers: Partial<Record<Method, CompiledHandler<CTX>>>;
 }
 export interface RequestCtx {
+    /**
+     * Server instance.
+     */
     server: Server;
+    /**
+     * Logger instance.
+     */
     logger: ILogger;
+    /**
+     * Parsed request URL.
+     *
+     * @remarks
+     * Route handlers SHOULD only use this url instead of
+     * {@link RequestCtx.req}'s `.url` property. This ensures, that the
+     * hash-fragment (`#...`) part is properly dealt with, avoiding security
+     * issues related to HTTP `request-target`
+     * (https://datatracker.ietf.org/doc/html/rfc9112#section-3.2).
+     *
+     * Note: The server already responds to any request containing a `#` in its
+     * URL with a HTTP 400.
+     *
+     * Also see {@link RequestCtx.path} and {@link RequestCtx.query}.
+     */
+    url: URL;
+    /**
+     * HTTP request instance.
+     */
     req: IncomingMessage;
+    /**
+     * HTTP server response instance.
+     */
     res: ServerResponse;
+    /**
+     * Pre-compiled route handler and its interceptors
+     */
     route: CompiledServerRoute;
+    /**
+     * Parsed route details.
+     */
     match: RouteMatch;
+    /**
+     * Request method (possibly adapted). Also see {@link RequestCtx.origMethod}.
+     */
     method: Method;
+    /**
+     * Original request method. Also see {@link RequestCtx.method}.
+     */
     origMethod: Method;
+    /**
+     * URI-decoded path part of request URL.
+     */
     path: string;
+    /**
+     * Parsed query string params (aka URL search params).
+     */
     query: Record<string, any>;
+    /**
+     * Parsed cookies, if any.
+     */
     cookies?: Record<string, string>;
+    /**
+     * Server session (only if {@link SessionInterceptor} is used).
+     */
     session?: ServerSession;
 }
 export type HandlerResult = MaybePromise<void>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/server",
-  "version": "0.9.1",
+  "version": "0.10.1",
   "description": "Minimal HTTP server with declarative routing, static file serving and freely extensible via pre/post interceptors",
   "type": "module",
   "module": "./index.js",
@@ -39,26 +39,26 @@
     "tool:tangle": "../../node_modules/.bin/tangle src/**/*.ts"
   },
   "dependencies": {
-    "@thi.ng/api": "^8.11.25",
-    "@thi.ng/arrays": "^2.10.22",
-    "@thi.ng/cache": "^2.3.30",
-    "@thi.ng/checks": "^3.7.5",
-    "@thi.ng/errors": "^2.5.31",
-    "@thi.ng/file-io": "^2.1.34",
-    "@thi.ng/leaky-bucket": "^0.2.3",
-    "@thi.ng/logger": "^3.1.6",
-    "@thi.ng/mime": "^2.7.7",
-    "@thi.ng/paths": "^5.2.8",
-    "@thi.ng/router": "^4.1.25",
-    "@thi.ng/strings": "^3.9.10",
-    "@thi.ng/timestamp": "^1.1.10",
-    "@thi.ng/uuid": "^1.1.22"
+    "@thi.ng/api": "^8.11.27",
+    "@thi.ng/arrays": "^2.11.0",
+    "@thi.ng/cache": "^2.3.32",
+    "@thi.ng/checks": "^3.7.7",
+    "@thi.ng/errors": "^2.5.33",
+    "@thi.ng/file-io": "^2.1.36",
+    "@thi.ng/leaky-bucket": "^0.2.5",
+    "@thi.ng/logger": "^3.1.8",
+    "@thi.ng/mime": "^2.7.9",
+    "@thi.ng/paths": "^5.2.10",
+    "@thi.ng/router": "^4.1.27",
+    "@thi.ng/strings": "^3.9.12",
+    "@thi.ng/timestamp": "^1.1.12",
+    "@thi.ng/uuid": "^1.1.24"
   },
   "devDependencies": {
-    "@types/node": "^22.13.14",
-    "esbuild": "^0.25.2",
-    "typedoc": "^0.28.1",
-    "typescript": "^5.8.2"
+    "@types/node": "^22.15.3",
+    "esbuild": "^0.25.3",
+    "typedoc": "^0.28.3",
+    "typescript": "^5.8.3"
   },
   "keywords": [
     "cookie",
@@ -167,5 +167,5 @@
     "status": "alpha",
     "year": 2024
   },
-  "gitHead": "87aa2d0e64a357476c10fd57aabdfded13c79f7d\n"
+  "gitHead": "4354686a6fb1f82c09ea48f92f87786191b231a0\n"
 }

package/server.js

@@ -90,6 +90,7 @@ class Server {
   }
   async listener(req, res) {
     try {
+      if (req.url.includes("#")) return res.badRequest();
       const url = new URL(req.url, `http://${req.headers.host}`);
       if (this.opts.host && !isMatchingHost(url.hostname, this.host)) {
         this.logger.debug(
@@ -123,6 +124,7 @@ class Server {
         // @ts-ignore
         server: this,
         logger: this.logger,
+        url,
         req,
         res,
         path,

package/interceptors/static.d.ts

@@ -1,96 +0,0 @@
-import type { Fn, MaybePromise, Predicate } from "@thi.ng/api";
-import { type HashAlgo } from "@thi.ng/file-io";
-import type { OutgoingHttpHeaders } from "node:http";
-import type { Interceptor, RequestCtx, ServerRoute } from "./api.js";
-/**
- * Static file configuration options.
- */
-export interface StaticOpts<CTX extends RequestCtx = RequestCtx> {
-	/**
-	 * Path to local root directory for static assets. Also see
-	 * {@link StaticOpts.prefix}
-	 *
-	 * @defaultValue `.` (current cwd)
-	 */
-	rootDir: string;
-	/**
-	 * Filter predicate to exclude files from being served. Called with the
-	 * absolute local file path. If the function returns false, the server
-	 * produces a 404 response. By default all files (within
-	 * {@link StaticOpts.rootDir}) will be allowed.
-	 */
-	filter: Predicate<string>;
-	/**
-	 * Base URL prefix for static assets.  Also see {@link StaticOpts.rootDir}
-	 *
-	 * @defaultValue "static"
-	 */
-	prefix: string;
-	/**
-	 * Additional route specific interceptors.
-	 */
-	intercept: Interceptor<CTX>[];
-	/**
-	 * Additional common headers (e.g. cache control) for all static files
-	 */
-	headers: OutgoingHttpHeaders;
-	/**
-	 * If true (default: false), files will be served with brotli, gzip or deflate
-	 * compression (if the client supports it).
-	 *
-	 * @defaultValue false
-	 */
-	compress: boolean;
-	/**
-	 * User defined function to compute an Etag value for given file path. The
-	 * file is guaranteed to exist when this function is called.
-	 */
-	etag: Fn<string, MaybePromise<string>>;
-	/**
-	 * If true, the route will have its `auth` flag enabled, e.g. for use with
-	 * the {@link authenticateWith} interceptor.
-	 *
-	 * @defaultValue false
-	 */
-	auth: boolean;
-}
-/**
- * Defines a configurable {@link ServerRoute} and handler for serving static
- * files from a local directory (optionally with compression, see
- * {@link StaticOpts.compress} for details).
- *
- * @param opts
- */
-export declare const staticFiles: <CTX extends RequestCtx = RequestCtx>({
-	prefix,
-	rootDir,
-	intercept,
-	filter,
-	compress,
-	auth,
-	etag,
-	headers,
-}?: Partial<StaticOpts<CTX>>) => ServerRoute<CTX>;
-/**
- * Etag header value function for {@link StaticOpts.etag}. Computes Etag based
- * on file modified date.
- *
- * @remarks
- * Also see {@link etagFileHash}.
- *
- * @param path
- */
-export declare const etagFileTimeModified: (path: string) => string;
-/**
- * Higher-order Etag header value function for {@link StaticOpts.etag}. Computes
- * Etag value by computing the hash digest of a given file. Uses MD5 by default.
- *
- * @remarks
- * Also see {@link etagFileTimeModified}.
- *
- * @param algo
- */
-export declare const etagFileHash: (
-	algo?: HashAlgo
-) => (path: string) => Promise<string>;
-//# sourceMappingURL=static.d.ts.map

package/interceptors/static.js

@@ -1,73 +0,0 @@
-import { fileHash as $fileHash } from "@thi.ng/file-io";
-import { preferredTypeForPath } from "@thi.ng/mime";
-import { existsSync, statSync } from "node:fs";
-import { join } from "node:path";
-import { isUnmodified } from "../utils/cache.js";
-const staticFiles = ({
-  prefix = "static",
-  rootDir = ".",
-  intercept = [],
-  filter = () => true,
-  compress = false,
-  auth = false,
-  etag,
-  headers
-} = {}) => ({
-  id: "__static",
-  match: [prefix, "+"],
-  auth,
-  handlers: {
-    head: {
-      fn: async (ctx) => {
-        const path = join(rootDir, ...ctx.match.rest);
-        ctx.logger.debug("path", path);
-        const $headers = await __fileHeaders(
-          path,
-          ctx,
-          filter,
-          etag,
-          headers
-        );
-        if (!$headers) return;
-        ctx.res.writeHead(200, {
-          "content-type": preferredTypeForPath(path),
-          ...$headers
-        });
-      },
-      intercept
-    },
-    get: {
-      fn: async (ctx) => {
-        const path = join(rootDir, ...ctx.match.rest);
-        ctx.logger.debug("path", path);
-        const $headers = await __fileHeaders(
-          path,
-          ctx,
-          filter,
-          etag,
-          headers
-        );
-        if (!$headers) return;
-        return ctx.server.sendFile(ctx, path, $headers, compress);
-      },
-      intercept
-    }
-  }
-});
-const __fileHeaders = async (path, ctx, filter, etag, headers) => {
-  if (!(existsSync(path) && filter(path))) {
-    return ctx.res.missing();
-  }
-  if (etag) {
-    const etagValue = await etag(path);
-    return isUnmodified(etagValue, ctx.req.headers["if-none-match"]) ? ctx.res.unmodified() : { ...headers, etag: etagValue };
-  }
-  return { ...headers };
-};
-const etagFileTimeModified = (path) => String(statSync(path).mtimeMs);
-const etagFileHash = (algo = "md5") => (path) => $fileHash(path, void 0, algo);
-export {
-  etagFileHash,
-  etagFileTimeModified,
-  staticFiles
-};