@thi.ng/server 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2025-01-30T15:45:22Z
+- **Last updated**: 2025-02-10T21:44:04Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -11,6 +11,43 @@ 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.4.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/server@0.4.0) (2025-02-10)
+
+#### 🚀 Features
+
+- update ServerSession & interceptor ([71d26bb](https://github.com/thi-ng/umbrella/commit/71d26bb))
+  - add `ServerSession.ip`
+  - update `SessionInterceptor` to validate stored IP addr
+  - rename `.delete()` => `.deleteSession()`
+  - add `.replaceSession()`
+  - remove obsolete `FlashMsg` (for now)
+- update ServerResponse, update host matching ([25a07f3](https://github.com/thi-ng/umbrella/commit/25a07f3))
+  - update `isMatchingHost()`
+  - add `ServerResponse.rateLimit()` and `.noResponse()`
+  - update tests
+- update SessionInterceptor to create signed cookie ([d240107](https://github.com/thi-ng/umbrella/commit/d240107))
+  - add `SessionOpts.secret`
+  - sign session ID with salt & SHA256
+  - add validateSession()
+  - update pre() interceptor
+- add `rateLimiter()` interceptor ([245cc9d](https://github.com/thi-ng/umbrella/commit/245cc9d))
+- add `measure()` interceptor ([4702e84](https://github.com/thi-ng/umbrella/commit/4702e84))
+  - refactor logRequest/Response() interceptors
+
+#### ⏱ Performance improvements
+
+- update Server 404 & OPTIONS handling, remove method override ([71307af](https://github.com/thi-ng/umbrella/commit/71307af))
+  - process 404 asap (without full request ctx)
+  - process default HTTP OPTIONS handler asap
+  - in both cases no interceptors will be run anymore
+
+## [0.3.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/server@0.3.0) (2025-02-02)
+
+#### 🚀 Features
+
+- add more HTTP error response methods ([5731ff3](https://github.com/thi-ng/umbrella/commit/5731ff3))
+- add ServerResponse, IPv6 support ([22f64c5](https://github.com/thi-ng/umbrella/commit/22f64c5))
+
 ## [0.2.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/server@0.2.0) (2025-01-30)
 
 #### 🚀 Features

package/README.md

@@ -75,8 +75,10 @@ for more details.
 - [`crossOriginOpenerPolicy()`](https://docs.thi.ng/umbrella/server/functions/crossOriginOpenerPolicy-1.html): Policy header injection
 - [`crossOriginResourcePolicy()`](https://docs.thi.ng/umbrella/server/functions/crossOriginResourcePolicy-1.html): Policy header injection
 - [`injectHeaders()`](https://docs.thi.ng/umbrella/server/functions/injectHeaders.html): Arbitrary header injection
+- [`measure()`](https://docs.thi.ng/umbrella/server/functions/measure.html): Request process timing info
 - [`logRequest()`](https://docs.thi.ng/umbrella/server/functions/logRequest.html): Request detail logging
 - [`logResponse()`](https://docs.thi.ng/umbrella/server/functions/logResponse.html): Response logging
+- [`rateLimiter()`](https://docs.thi.ng/umbrella/server/functions/rateLimiter-1.html): Configurable rate limiting
 - [`referrerPolicy()`](https://docs.thi.ng/umbrella/server/functions/referrerPolicy-1.html): Policy header injection
 - [`serverSession()`](https://docs.thi.ng/umbrella/server/functions/serverSession-1.html): User defined in-memory sessions with TTL
 - [`strictTransportSecurity()`](https://docs.thi.ng/umbrella/server/functions/strictTransportSecurity.html): Policy header injection
@@ -147,7 +149,7 @@ For Node.js REPL:
 const ser = await import("@thi.ng/server");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 4.02 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 5.24 KB
 
 ## Dependencies
 
@@ -162,6 +164,7 @@ Package sizes (brotli'd, pre-treeshake): ESM: 4.02 KB
 - [@thi.ng/paths](https://github.com/thi-ng/umbrella/tree/develop/packages/paths)
 - [@thi.ng/router](https://github.com/thi-ng/umbrella/tree/develop/packages/router)
 - [@thi.ng/strings](https://github.com/thi-ng/umbrella/tree/develop/packages/strings)
+- [@thi.ng/timestamp](https://github.com/thi-ng/umbrella/tree/develop/packages/timestamp)
 - [@thi.ng/uuid](https://github.com/thi-ng/umbrella/tree/develop/packages/uuid)
 
 Note: @thi.ng/api is in _most_ cases a type-only import (not used at runtime)
@@ -229,10 +232,12 @@ const app = srv.server<AppCtx>({
                     const { user, pass } = await srv.parseRequestFormData(ctx.req);
                     ctx.logger.info("login details", user, pass);
                     if (user === "thi.ng" && pass === "1234") {
-                        ctx.session!.user = user;
+                        // create new session for security reasons (session fixation)
+                        const newSession = await session.replaceSession(ctx)!;
+                        newSession!.user = user;
                         ctx.res.writeHead(200).end("logged in as " + user);
                     } else {
-                        ctx.res.writeHead(403).end("login failed");
+                        ctx.res.unauthorized({}, "login failed");
                     }
                 },
             },
@@ -246,7 +251,7 @@ const app = srv.server<AppCtx>({
             handlers: {
                 get: async (ctx) => {
                     // remove session & force expire session cookie
-                    await session.delete(ctx, ctx.session!.id);
+                    await session.deleteSession(ctx, ctx.session!.id);
                     ctx.res.writeHead(200).end("logged out");
                 },
             },

package/api.d.ts

@@ -1,8 +1,8 @@
 import type { Fn, Maybe, MaybePromise } from "@thi.ng/api";
 import type { ILogger } from "@thi.ng/logger";
 import type { Route, RouteMatch } from "@thi.ng/router";
-import type { IncomingMessage, ServerResponse } from "node:http";
-import type { Server } from "./server.js";
+import type { IncomingMessage } from "node:http";
+import type { ServerResponse, Server } from "./server.js";
 export type Method = "get" | "put" | "post" | "delete" | "head" | "options" | "patch";
 export interface ServerOpts<CTX extends RequestCtx = RequestCtx> {
     logger: ILogger;
@@ -119,12 +119,18 @@ export interface Interceptor<CTX extends RequestCtx = RequestCtx> {
     post?: Fn<CTX, InterceptorResult>;
 }
 export interface ServerSession {
+    /**
+     * Unique session ID
+     */
     id: string;
-    flash?: FlashMsg;
-}
-export interface FlashMsg {
-    type: "success" | "info" | "warn" | "error";
-    body: any;
+    /**
+     * Client's remote IP address when session was originally created. To
+     * counteract session fixation, each request's remote address is being
+     * checked (by {@link SessionInterceptor.pre}) against this stored address.
+     * If there's a mismatch between the two, then a new session will be
+     * generated automatically.
+     */
+    ip: string;
 }
 export interface ISessionStore<T extends ServerSession = ServerSession> {
     /**

package/index.d.ts

@@ -5,6 +5,8 @@ export * from "./interceptors/auth-route.js";
 export * from "./interceptors/cache-control.js";
 export * from "./interceptors/inject-headers.js";
 export * from "./interceptors/logging.js";
+export * from "./interceptors/measure.js";
+export * from "./interceptors/rate-limit.js";
 export * from "./interceptors/referrer-policy.js";
 export * from "./interceptors/strict-transport.js";
 export * from "./interceptors/x-origin-opener.js";
@@ -13,6 +15,7 @@ export * from "./session/session.js";
 export * from "./session/memory.js";
 export * from "./utils/cookies.js";
 export * from "./utils/cache.js";
+export * from "./utils/host.js";
 export * from "./utils/formdata.js";
 export * from "./utils/multipart.js";
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -5,6 +5,8 @@ export * from "./interceptors/auth-route.js";
 export * from "./interceptors/cache-control.js";
 export * from "./interceptors/inject-headers.js";
 export * from "./interceptors/logging.js";
+export * from "./interceptors/measure.js";
+export * from "./interceptors/rate-limit.js";
 export * from "./interceptors/referrer-policy.js";
 export * from "./interceptors/strict-transport.js";
 export * from "./interceptors/x-origin-opener.js";
@@ -13,5 +15,6 @@ export * from "./session/session.js";
 export * from "./session/memory.js";
 export * from "./utils/cookies.js";
 export * from "./utils/cache.js";
+export * from "./utils/host.js";
 export * from "./utils/formdata.js";
 export * from "./utils/multipart.js";

package/interceptors/auth-route.js

@@ -1,7 +1,7 @@
 const authenticateWith = (pred) => ({
   pre: (ctx) => {
     if (ctx.route.auth && !pred(ctx)) {
-      ctx.server.unauthorized(ctx.res);
+      ctx.res.unauthorized();
       return false;
     }
     return true;

package/interceptors/logging.js

@@ -1,8 +1,6 @@
-import { isString } from "@thi.ng/checks";
-import { LogLevel } from "@thi.ng/logger";
-const __method = (level) => (isString(level) ? level : LogLevel[level]).toLowerCase();
+import { LogLevel, methodForLevel } from "@thi.ng/logger";
 const logRequest = (level = "INFO") => {
-  const method = __method(level);
+  const method = methodForLevel(level);
   return {
     pre: ({ logger, req, match, query, cookies }) => {
       logger[method]("request route", req.method, match);
@@ -14,7 +12,7 @@ const logRequest = (level = "INFO") => {
   };
 };
 const logResponse = (level = "INFO") => {
-  const method = __method(level);
+  const method = methodForLevel(level);
   return {
     post: ({ logger, match, res }) => {
       logger[method]("response status", res.statusCode, match);

package/interceptors/measure.d.ts

@@ -0,0 +1,9 @@
+import { type LogLevel, type LogLevelName } from "@thi.ng/logger";
+import type { Interceptor } from "../api.js";
+/**
+ * Pre/post interceptor to measure & log a request's processing time.
+ *
+ * @param level
+ */
+export declare const measure: (level?: LogLevel | LogLevelName) => Interceptor;
+//# sourceMappingURL=measure.d.ts.map

package/interceptors/measure.js

@@ -0,0 +1,27 @@
+import {
+  methodForLevel
+} from "@thi.ng/logger";
+import { now, timeDiff } from "@thi.ng/timestamp";
+const measure = (level = "DEBUG") => {
+  const requests = /* @__PURE__ */ new WeakMap();
+  const method = methodForLevel(level);
+  return {
+    pre: (ctx) => {
+      requests.set(ctx, now());
+      return true;
+    },
+    post: (ctx) => {
+      const t0 = requests.get(ctx);
+      if (t0) {
+        requests.delete(ctx);
+        ctx.logger[method](
+          `request processed in: ${timeDiff(t0).toFixed(3)}ms`
+        );
+      }
+      return true;
+    }
+  };
+};
+export {
+  measure
+};

package/interceptors/rate-limit.d.ts

@@ -0,0 +1,73 @@
+import type { Fn, Fn2, Maybe } from "@thi.ng/api";
+import { TLRUCache } from "@thi.ng/cache";
+import type { Interceptor, RequestCtx } from "../api.js";
+export interface RateLimitOpts<T extends RequestCtx = RequestCtx> {
+    /**
+     * Function to produce a unique ID for rate limiting a client. By default
+     * uses client's remote IP address. If this function returns undefined, the
+     * client will NOT be rate limited.
+     */
+    id?: Fn<T, Maybe<string>>;
+    /**
+     * Function to compute the max number of allowed requests for given client
+     * ID and configured {@link RateLimitOpts.period}. If given as number, that
+     * limit will be enforced for all identified clients.
+     *
+     * @remarks
+     * Quotas are only computed whenever a new client ID is first encountered or
+     * when its previous request records have expired from the cache (after
+     * {@link RateLimitOpts.period} seconds).
+     */
+    quota: number | Fn2<T, string, number>;
+    /**
+     * Size of the time window (in secords) to which this rate limiter applies.
+     *
+     * @defaultValue 900
+     */
+    period?: number;
+}
+/**
+ * Creates a new {@link RateLimiter} interceptor.
+ *
+ * @param opts
+ */
+export declare const rateLimiter: <T extends RequestCtx = RequestCtx>(opts: RateLimitOpts<T>) => RateLimiter<T>;
+/**
+ * Configurable, sliding time window-based rate limiter interceptor.
+ */
+export declare class RateLimiter<T extends RequestCtx = RequestCtx> implements Interceptor<T> {
+    cache: TLRUCache<string, Timestamps>;
+    clientQuota: Fn2<T, string, number>;
+    clientID: Fn<T, Maybe<string>>;
+    period: number;
+    constructor({ id, quota, period }: RateLimitOpts<T>);
+    pre(ctx: T): boolean;
+}
+/**
+ * Ring-buffer based history of request timestamps (per client).
+ *
+ * @remarks
+ * Based on thi.ng/buffers `FIFOBuffer` implementation.
+ *
+ * @internal
+ */
+declare class Timestamps {
+    quota: number;
+    buf: number[];
+    rpos: number;
+    wpos: number;
+    num: number;
+    constructor(quota: number);
+    /**
+     * Removes any timestamps older than `threshold` from the buffer and returns
+     * remaining number of timestamps.
+     *
+     * @param threshold
+     */
+    expire(threshold: number): number;
+    peek(): number;
+    writable(): boolean;
+    write(x: number): boolean;
+}
+export {};
+//# sourceMappingURL=rate-limit.d.ts.map

package/interceptors/rate-limit.js

@@ -0,0 +1,82 @@
+import { TLRUCache } from "@thi.ng/cache";
+import { isNumber } from "@thi.ng/checks";
+const rateLimiter = (opts) => new RateLimiter(opts);
+class RateLimiter {
+  cache;
+  clientQuota;
+  clientID;
+  period;
+  constructor({ id, quota, period = 15 * 60 }) {
+    this.clientID = id ?? ((ctx) => ctx.req.socket.remoteAddress);
+    this.clientQuota = isNumber(quota) ? () => quota : quota;
+    this.period = (period ?? 15 * 60) * 1e3;
+    this.cache = new TLRUCache(null, {
+      ttl: this.period,
+      autoExtend: true
+    });
+  }
+  pre(ctx) {
+    const now = Date.now();
+    const id = this.clientID(ctx);
+    if (!id) return true;
+    let timestamps = this.cache.get(id);
+    if (timestamps) {
+      if (timestamps.expire(now - this.period) >= timestamps.quota) {
+        ctx.res.rateLimit(
+          {},
+          `Try again @ ${new Date(
+            timestamps.peek() + this.period
+          ).toISOString()}`
+        );
+        return false;
+      }
+    } else {
+      timestamps = new Timestamps(this.clientQuota(ctx, id));
+      this.cache.set(id, timestamps);
+    }
+    timestamps.write(now);
+    return true;
+  }
+}
+class Timestamps {
+  constructor(quota) {
+    this.quota = quota;
+  }
+  buf = [];
+  rpos = 0;
+  wpos = 0;
+  num = 0;
+  /**
+   * Removes any timestamps older than `threshold` from the buffer and returns
+   * remaining number of timestamps.
+   *
+   * @param threshold
+   */
+  expire(threshold) {
+    let { buf, rpos, num } = this;
+    const max = buf.length;
+    while (num && buf[rpos] < threshold) {
+      rpos = (rpos + 1) % max;
+      num--;
+    }
+    this.rpos = rpos;
+    return this.num = num;
+  }
+  peek() {
+    return this.buf[this.rpos];
+  }
+  writable() {
+    return this.num < this.quota;
+  }
+  write(x) {
+    const { buf, wpos } = this;
+    buf[wpos] = x;
+    this.wpos = (wpos + 1) % this.quota;
+    this.num++;
+    return true;
+  }
+}
+export {
+  RateLimiter,
+  rateLimiter
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/server",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Minimal HTTP server with declarative routing, static file serving and freely extensible via pre/post interceptors",
   "type": "module",
   "module": "./index.js",
@@ -44,12 +44,13 @@
     "@thi.ng/cache": "^2.3.22",
     "@thi.ng/checks": "^3.6.22",
     "@thi.ng/errors": "^2.5.25",
-    "@thi.ng/file-io": "^2.1.25",
-    "@thi.ng/logger": "^3.0.30",
-    "@thi.ng/mime": "^2.7.0",
+    "@thi.ng/file-io": "^2.1.26",
+    "@thi.ng/logger": "^3.1.0",
+    "@thi.ng/mime": "^2.7.1",
     "@thi.ng/paths": "^5.2.0",
     "@thi.ng/router": "^4.1.17",
     "@thi.ng/strings": "^3.9.4",
+    "@thi.ng/timestamp": "^1.1.4",
     "@thi.ng/uuid": "^1.1.16"
   },
   "devDependencies": {
@@ -112,6 +113,12 @@
     "./interceptors/logging": {
       "default": "./interceptors/logging.js"
     },
+    "./interceptors/measure": {
+      "default": "./interceptors/measure.js"
+    },
+    "./interceptors/rate-limit": {
+      "default": "./interceptors/rate-limit.js"
+    },
     "./interceptors/referrer-policy": {
       "default": "./interceptors/referrer-policy.js"
     },
@@ -145,6 +152,9 @@
     "./utils/formdata": {
       "default": "./utils/formdata.js"
     },
+    "./utils/host": {
+      "default": "./utils/host.js"
+    },
     "./utils/multipart": {
       "default": "./utils/multipart.js"
     }
@@ -153,5 +163,5 @@
     "status": "alpha",
     "year": 2024
   },
-  "gitHead": "078de98f4365f0d472c87198bcd6a112e732d9ef\n"
+  "gitHead": "dcc1dbfa6eae31ac65e12843987b94d4a7edc144\n"
 }

package/server.d.ts

@@ -7,21 +7,39 @@ export declare class Server<CTX extends RequestCtx = RequestCtx> {
     opts: Partial<ServerOpts<CTX>>;
     logger: ILogger;
     router: Router<CompiledServerRoute<CTX>>;
-    server: http.Server;
+    server: http.Server<typeof http.IncomingMessage, typeof ServerResponse>;
+    host: string;
     protected augmentCtx: Fn<RequestCtx, CTX>;
     constructor(opts?: Partial<ServerOpts<CTX>>);
     start(): Promise<boolean>;
     stop(): Promise<boolean>;
-    protected listener(req: http.IncomingMessage, res: http.ServerResponse): Promise<void>;
+    protected listener(req: http.IncomingMessage, res: ServerResponse): Promise<void>;
     protected runHandler({ fn, pre, post }: CompiledHandler, ctx: CTX): Promise<void>;
     protected compileRoute(route: ServerRoute<CTX>): CompiledServerRoute<CTX>;
-    addRoutes(routes: ServerRoute[]): void;
+    addRoutes(routes: ServerRoute<CTX>[]): void;
     sendFile({ req, res }: RequestCtx, path: string, headers?: http.OutgoingHttpHeaders, compress?: boolean): Promise<void>;
-    unauthorized(res: http.ServerResponse): void;
-    unmodified(res: http.ServerResponse): void;
-    missing(res: http.ServerResponse): void;
-    redirectTo(res: http.ServerResponse, location: string): void;
-    redirectToRoute(res: http.ServerResponse, route: RouteMatch): void;
+    redirectToRoute(res: ServerResponse, route: RouteMatch): void;
 }
 export declare const server: <CTX extends RequestCtx>(opts?: Partial<ServerOpts<CTX>>) => Server<CTX>;
+/**
+ * Extended version of the default NodeJS ServerResponse with additional methods
+ * for various commonly used HTTP statuses/errors.
+ */
+export declare class ServerResponse extends http.ServerResponse<http.IncomingMessage> {
+    noContent(headers?: http.OutgoingHttpHeaders): void;
+    redirectTo(location: string, headers?: http.OutgoingHttpHeaders): void;
+    seeOther(location: string, headers?: http.OutgoingHttpHeaders): void;
+    unmodified(headers?: http.OutgoingHttpHeaders): void;
+    unauthorized(headers?: http.OutgoingHttpHeaders, body?: any): void;
+    forbidden(headers?: http.OutgoingHttpHeaders, body?: any): void;
+    missing(headers?: http.OutgoingHttpHeaders, body?: any): void;
+    notAllowed(headers?: http.OutgoingHttpHeaders, body?: any): void;
+    notAcceptable(headers?: http.OutgoingHttpHeaders, body?: any): void;
+    rateLimit(headers?: http.OutgoingHttpHeaders, body?: any): void;
+    /**
+     * HTTP 444. Indicates the server has returned no information to the client and closed
+     * the connection (useful as a deterrent for malware)
+     */
+    noResponse(): void;
+}
 //# sourceMappingURL=server.d.ts.map

package/server.js

@@ -4,26 +4,30 @@ import { readText } from "@thi.ng/file-io";
 import { ConsoleLogger } from "@thi.ng/logger";
 import { preferredTypeForPath } from "@thi.ng/mime";
 import { Router } from "@thi.ng/router";
+import { upper } from "@thi.ng/strings";
 import { createReadStream } from "node:fs";
 import * as http from "node:http";
 import * as https from "node:https";
+import { isIPv6 } from "node:net";
 import { pipeline, Transform } from "node:stream";
 import { createBrotliCompress, createDeflate, createGzip } from "node:zlib";
 import { parseCoookies } from "./utils/cookies.js";
 import { parseSearchParams } from "./utils/formdata.js";
-import { upper } from "@thi.ng/strings";
+import { isMatchingHost, normalizeIPv6Address } from "./utils/host.js";
 const MISSING = "__missing";
 class Server {
   constructor(opts = {}) {
     this.opts = opts;
     this.logger = opts.logger ?? new ConsoleLogger("server");
+    this.host = opts.host ?? "localhost";
+    if (isIPv6(this.host)) this.host = normalizeIPv6Address(this.host);
     this.augmentCtx = opts.context ?? identity;
     const routes = [
       {
         id: MISSING,
         match: ["__404__"],
         handlers: {
-          get: async ({ res }) => this.missing(res)
+          get: async ({ res }) => res.missing()
         }
       },
       ...this.opts.routes ?? []
@@ -38,19 +42,22 @@ class Server {
   logger;
   router;
   server;
+  host;
   augmentCtx;
   async start() {
-    const ssl = this.opts.ssl;
-    const port = this.opts.port ?? (ssl ? 443 : 8080);
-    const host = this.opts.host ?? "localhost";
+    const { ssl, host = "localhost", port = ssl ? 443 : 8080 } = this.opts;
     try {
       this.server = ssl ? https.createServer(
         {
           key: readText(ssl.key, this.logger),
-          cert: readText(ssl.cert, this.logger)
+          cert: readText(ssl.cert, this.logger),
+          ServerResponse
         },
         this.listener.bind(this)
-      ) : http.createServer({}, this.listener.bind(this));
+      ) : http.createServer(
+        { ServerResponse },
+        this.listener.bind(this)
+      );
       this.server.listen(port, host, void 0, () => {
         this.logger.info(
           `starting server: http${ssl ? "s" : ""}://${host}:${port}`
@@ -70,18 +77,29 @@ class Server {
     return true;
   }
   async listener(req, res) {
-    const url = new URL(req.url, `http://${req.headers.host}`);
-    if (this.opts.host && this.opts.host !== url.host) {
-      res.writeHead(503).end();
-      return;
-    }
-    const path = decodeURIComponent(url.pathname);
     try {
-      const query = parseSearchParams(url.searchParams);
+      const url = new URL(req.url, `http://${req.headers.host}`);
+      if (this.opts.host && !isMatchingHost(url.hostname, this.host)) {
+        this.logger.debug(
+          "ignoring request, host mismatch:",
+          url.hostname,
+          this.host
+        );
+        return res.noResponse();
+      }
+      const path = decodeURIComponent(url.pathname);
       const match = this.router.route(path);
+      if (match.id === MISSING) return res.missing();
       const route = this.router.routeForID(match.id).spec;
+      let method = req.method.toLowerCase();
+      if (method === "options" && !route.handlers.options) {
+        return res.noContent({
+          allow: Object.keys(route.handlers).map(upper).join(", ")
+        });
+      }
       const rawCookies = req.headers["cookie"] || req.headers["set-cookie"]?.join(";");
       const cookies = rawCookies ? parseCoookies(rawCookies) : {};
+      const query = parseSearchParams(url.searchParams);
       const ctx = this.augmentCtx({
         // @ts-ignore
         server: this,
@@ -94,17 +112,6 @@ class Server {
         route,
         match
       });
-      if (match.id === MISSING) {
-        this.runHandler(route.handlers.get, ctx);
-        return;
-      }
-      let method = ctx.query?.__method || req.method.toLowerCase();
-      if (method === "options" && !route.handlers.options) {
-        res.writeHead(204, {
-          allow: Object.keys(route.handlers).map(upper).join(", ")
-        }).end();
-        return;
-      }
       if (method === "head" && !route.handlers.head && route.handlers.get) {
         method = "get";
       }
@@ -112,7 +119,7 @@ class Server {
       if (handler) {
         this.runHandler(handler, ctx);
       } else {
-        res.writeHead(405).end();
+        res.notAllowed();
       }
     } catch (e) {
       this.logger.warn("error:", e.message);
@@ -196,29 +203,57 @@ class Server {
         encoding ? pipeline(src, encoding.tx(), res, finalize) : pipeline(src, res, finalize);
       } catch (e) {
         this.logger.warn(e.message);
-        this.missing(res);
+        res.missing();
         resolve();
       }
     });
   }
-  unauthorized(res) {
-    res.writeHead(403, "Forbidden").end();
+  redirectToRoute(res, route) {
+    res.redirectTo(this.router.format(route));
   }
-  unmodified(res) {
-    res.writeHead(304, "Not modified").end();
+}
+const server = (opts) => new Server(opts);
+class ServerResponse extends http.ServerResponse {
+  noContent(headers) {
+    this.writeHead(204, headers).end();
   }
-  missing(res) {
-    res.writeHead(404, "Not found").end();
+  redirectTo(location, headers) {
+    this.writeHead(302, { ...headers, location }).end();
   }
-  redirectTo(res, location) {
-    res.writeHead(302, { location }).end();
+  seeOther(location, headers) {
+    this.writeHead(303, { ...headers, location }).end();
   }
-  redirectToRoute(res, route) {
-    this.redirectTo(res, this.router.format(route));
+  unmodified(headers) {
+    this.writeHead(304, headers).end();
+  }
+  unauthorized(headers, body) {
+    this.writeHead(401, headers).end(body);
+  }
+  forbidden(headers, body) {
+    this.writeHead(403, headers).end(body);
+  }
+  missing(headers, body) {
+    this.writeHead(404, headers).end(body);
+  }
+  notAllowed(headers, body) {
+    this.writeHead(405, headers).end(body);
+  }
+  notAcceptable(headers, body) {
+    this.writeHead(406, headers).end(body);
+  }
+  rateLimit(headers, body) {
+    this.writeHead(429, headers).end(body);
+  }
+  /**
+   * HTTP 444. Indicates the server has returned no information to the client and closed
+   * the connection (useful as a deterrent for malware)
+   */
+  noResponse() {
+    this.writeHead(444).end();
   }
 }
-const server = (opts) => new Server(opts);
 export {
   Server,
+  ServerResponse,
   server
 };

package/session/session.d.ts

@@ -3,14 +3,13 @@ import { ServerResponse } from "node:http";
 import type { Interceptor, ISessionStore, RequestCtx, ServerSession } from "../api.js";
 export interface SessionOpts<CTX extends RequestCtx = RequestCtx, SESSION extends ServerSession = ServerSession> {
     /**
-     * Session storage implementation. Default: {@link InMemorySessionStore}.
+     * Factory function to create a new session object. See {@link createSession}.
      */
-    store: ISessionStore<SESSION>;
+    factory: Fn<CTX, SESSION>;
     /**
-     * Factory function to create a new session object. By default the object
-     * only contains a {@link ServerSession.id} (UUID v4).
+     * Session storage implementation. Default: {@link InMemorySessionStore}.
      */
-    factory: Fn<CTX, SESSION>;
+    store?: ISessionStore<SESSION>;
     /**
      * Session cookie name
      *
@@ -23,21 +22,48 @@ export interface SessionOpts<CTX extends RequestCtx = RequestCtx, SESSION extend
      * @defaultValue "Secure;HttpOnly;SameSite=Strict;Path=/"
      */
     cookieOpts?: string;
+    /**
+     * HMAC key/secret used for signing cookies (using SHA256). Max length 64
+     * bytes. If given as number, generates N random bytes.
+     */
+    secret?: number | string | Buffer;
 }
 export declare class SessionInterceptor<CTX extends RequestCtx = RequestCtx, SESSION extends ServerSession = ServerSession> implements Interceptor<CTX> {
-    store: ISessionStore<SESSION>;
     factory: Fn<CTX, SESSION>;
+    store: ISessionStore<SESSION>;
     cookieName: string;
     cookieOpts: string;
-    constructor({ store, factory, cookieName, cookieOpts, }?: Partial<SessionOpts<CTX, SESSION>>);
+    secret: Buffer;
+    constructor({ factory, store, cookieName, cookieOpts, secret, }: SessionOpts<CTX, SESSION>);
     pre(ctx: CTX): Promise<boolean>;
-    delete(ctx: CTX, sessionID: string): Promise<void>;
-    withSession(res: ServerResponse, sessionID: string): void;
+    deleteSession(ctx: CTX, sessionID: string): Promise<void>;
+    newSession(ctx: CTX): Promise<SESSION | undefined>;
+    /**
+     * Calls {@link SessionInterceptor.newSession} to create a new session and,
+     * if successful, associates it with current context & response. Deletes
+     * existing session (if any). Returns new session object.
+     *
+     * @param ctx
+     */
+    replaceSession(ctx: CTX): Promise<SESSION | undefined>;
+    withSession(res: ServerResponse, sessionID: string): ServerResponse<import("http").IncomingMessage>;
+    validateSession(cookie: string): string | undefined;
 }
 /**
  * Factory function to create a new {@link SessionInterceptor} instance.
  *
  * @param opts
  */
-export declare const serverSession: <CTX extends RequestCtx = RequestCtx, SESSION extends ServerSession = ServerSession>(opts?: Partial<SessionOpts<CTX, SESSION>>) => SessionInterceptor<CTX, SESSION>;
+export declare const serverSession: <CTX extends RequestCtx = RequestCtx, SESSION extends ServerSession = ServerSession>(opts: SessionOpts<CTX, SESSION>) => SessionInterceptor<CTX, SESSION>;
+/**
+ * Creates a new basic {@link ServerSession}, using a UUID v4 for
+ * {@link ServerSession.id}.
+ *
+ * @remarks
+ * Intended to be used for {@link SessionOpts.factory} and/or as basis for
+ * creating custom session objects.
+ *
+ * @param ctx
+ */
+export declare const createSession: (ctx: RequestCtx) => ServerSession;
 //# sourceMappingURL=session.d.ts.map

package/session/session.js

@@ -1,36 +1,47 @@
+import { isNumber, isString } from "@thi.ng/checks";
 import { uuid } from "@thi.ng/uuid";
+import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
 import { ServerResponse } from "node:http";
 import { inMemorySessionStore } from "./memory.js";
 class SessionInterceptor {
-  store;
   factory;
+  store;
   cookieName;
   cookieOpts;
+  secret;
   constructor({
+    factory,
     store = inMemorySessionStore(),
-    factory = () => ({ id: uuid() }),
     cookieName = "__sid",
-    cookieOpts = "Secure;HttpOnly;SameSite=Strict;Path=/"
-  } = {}) {
-    this.store = store;
+    cookieOpts = "Secure;HttpOnly;SameSite=Strict;Path=/",
+    secret = 32
+  }) {
     this.factory = factory;
+    this.store = store;
+    this.secret = isNumber(secret) ? randomBytes(secret) : isString(secret) ? Buffer.from(secret) : secret;
     this.cookieName = cookieName;
     this.cookieOpts = cookieOpts;
   }
   async pre(ctx) {
-    const { res, logger, cookies } = ctx;
-    const id = cookies?.[this.cookieName];
+    const cookie = ctx.cookies?.[this.cookieName];
+    let id;
+    if (cookie) {
+      id = this.validateSession(cookie);
+      if (!id) {
+        ctx.res.forbidden();
+        return false;
+      }
+    }
     let session = id ? await this.store.get(id) : void 0;
-    if (!session) {
-      session = this.factory(ctx);
-      logger.info("new session:", session.id);
-      this.store.set(session);
+    if (!session || session.ip !== ctx.req.socket.remoteAddress) {
+      session = await this.newSession(ctx);
+      if (!session) return false;
     }
     ctx.session = session;
-    this.withSession(res, session.id);
+    this.withSession(ctx.res, session.id);
     return true;
   }
-  async delete(ctx, sessionID) {
+  async deleteSession(ctx, sessionID) {
     if (await this.store.delete(sessionID)) {
       ctx.logger.info("delete session:", sessionID);
       ctx.session = void 0;
@@ -40,15 +51,58 @@ class SessionInterceptor {
       );
     }
   }
+  async newSession(ctx) {
+    const session = this.factory(ctx);
+    ctx.logger.info("new session:", session.id);
+    if (!await this.store.set(session)) {
+      ctx.logger.warn("could not store session...");
+      return;
+    }
+    return session;
+  }
+  /**
+   * Calls {@link SessionInterceptor.newSession} to create a new session and,
+   * if successful, associates it with current context & response. Deletes
+   * existing session (if any). Returns new session object.
+   *
+   * @param ctx
+   */
+  async replaceSession(ctx) {
+    const session = await this.newSession(ctx);
+    if (session) {
+      if (ctx.session?.id) this.store.delete(ctx.session.id);
+      ctx.session = session;
+      this.withSession(ctx.res, session.id);
+      return session;
+    }
+  }
   withSession(res, sessionID) {
-    res.appendHeader(
+    const cookie = sessionID + ":" + randomBytes(8).toString("base64url");
+    const signature = createHmac("sha256", this.secret).update(cookie, "ascii").digest().toString("base64url");
+    return res.appendHeader(
       "set-cookie",
-      `${this.cookieName}=${sessionID};Max-Age=${this.store.ttl};${this.cookieOpts}`
+      `${this.cookieName}=${cookie}:${signature};Max-Age=${this.store.ttl};${this.cookieOpts}`
     );
   }
+  validateSession(cookie) {
+    const parts = cookie.split(":");
+    if (parts.length < 3) return;
+    const actual = Buffer.from(parts[2], "base64url");
+    const expected = createHmac("sha256", this.secret).update(
+      cookie.substring(0, cookie.length - parts[2].length - 1),
+      "ascii"
+    ).digest();
+    const sameLength = actual.length === expected.length;
+    return timingSafeEqual(sameLength ? actual : expected, expected) && sameLength ? parts[0] : void 0;
+  }
 }
 const serverSession = (opts) => new SessionInterceptor(opts);
+const createSession = (ctx) => ({
+  id: uuid(),
+  ip: ctx.req.socket.remoteAddress
+});
 export {
   SessionInterceptor,
+  createSession,
   serverSession
 };

package/static.js

@@ -54,11 +54,11 @@ const staticFiles = ({
 });
 const __fileHeaders = async (path, ctx, filter, etag, headers) => {
   if (!(existsSync(path) && filter(path))) {
-    return ctx.server.missing(ctx.res);
+    return ctx.res.missing();
   }
   if (etag) {
     const etagValue = await etag(path);
-    return isUnmodified(etagValue, ctx.req.headers["if-none-match"]) ? ctx.server.unmodified(ctx.res) : { ...headers, etag: etagValue };
+    return isUnmodified(etagValue, ctx.req.headers["if-none-match"]) ? ctx.res.unmodified() : { ...headers, etag: etagValue };
   }
   return { ...headers };
 };

package/utils/host.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Takes a hostname or IPv6 address `test` and compares it against `expected`,
+ * returns true if matching.
+ *
+ * @remarks
+ * If `test` is an IPv6 address in the format `[...]`, it will be compared
+ * without surrounding square brackets. If `expected` is an IPv6 address it MUST
+ * have been pre-normalized using {@link normalizeIPv6Address}. For performance
+ * reasons only `test` will be automatically normalized, i.e. `::1` will be
+ * normalized as `0:0:0:0:0:0:0:1`.
+ *
+ * @param test
+ * @param expected
+ *
+ * @internal
+ */
+export declare const isMatchingHost: (test: string, expected: string) => boolean;
+/**
+ * Parses given IPv6 address into an 8-tuple of 16bit uints. Throws error if
+ * address is invalid.
+ *
+ * @remarks
+ * https://en.wikipedia.org/wiki/IPv6_address
+ *
+ * @param addr
+ */
+export declare const parseIPv6Address: (addr: string) => number[];
+/**
+ * Returns normalized version of given IPv6 address, i.e. expanding `::`
+ * sections, removing leading zeroes and performing other syntactic validations.
+ * The returned address always has 8 parts. Throws error if address is invalid.
+ *
+ * @remarks
+ * Internally uses {@link parseIPv6Address}.
+ *
+ * Reference:
+ * https://en.wikipedia.org/wiki/IPv6_address
+ *
+ * @param addr
+ */
+export declare const normalizeIPv6Address: (addr: string) => string;
+//# sourceMappingURL=host.d.ts.map

package/utils/host.js

@@ -0,0 +1,49 @@
+import { illegalArgs } from "@thi.ng/errors";
+import { HEX } from "@thi.ng/strings";
+const isMatchingHost = (test, expected) => {
+  if (/^\[[0-9a-f:]{1,39}\]$/.test(test)) {
+    try {
+      return normalizeIPv6Address(test.substring(1, test.length - 1)) === expected;
+    } catch (_) {
+      return false;
+    }
+  }
+  return test === expected;
+};
+const parseIPv6Address = (addr) => {
+  if (addr == "::") return [0, 0, 0, 0, 0, 0, 0, 0];
+  if (addr == "::1") return [0, 0, 0, 0, 0, 0, 0, 1];
+  const n = addr.length - 1;
+  if (n > 38) invalidIPv6(addr);
+  const parts = [];
+  let curr = 0;
+  let zeroes = -1;
+  for (let i = 0; i <= n; i++) {
+    const ch = addr[i];
+    if (i === n && ch == ":") illegalArgs(addr);
+    if (i === n || ch === ":") {
+      if (parts.length >= (zeroes >= 0 ? 6 : 8)) invalidIPv6(addr);
+      const end = i === n ? n + 1 : i > curr ? i : invalidIPv6(addr);
+      if (end - curr > 4) invalidIPv6(addr);
+      parts.push(parseInt(addr.substring(curr, end), 16));
+      if (addr[i + 1] === ":") {
+        if (zeroes >= 0) invalidIPv6(addr);
+        zeroes = parts.length;
+        i++;
+      }
+      curr = i + 1;
+    } else if (!HEX[ch]) invalidIPv6(addr);
+  }
+  if (zeroes >= 0) {
+    parts.splice(zeroes, 0, ...new Array(8 - parts.length).fill(0));
+  }
+  if (parts.length !== 8) invalidIPv6(addr);
+  return parts;
+};
+const normalizeIPv6Address = (addr) => parseIPv6Address(addr).map((x) => x.toString(16)).join(":");
+const invalidIPv6 = (addr) => illegalArgs("invalid IPv6 address: " + addr);
+export {
+  isMatchingHost,
+  normalizeIPv6Address,
+  parseIPv6Address
+};