@thi.ng/server 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2025-02-19T20:59:58Z
+- **Last updated**: 2025-02-21T21:54:17Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -11,6 +11,18 @@ 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.6.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/server@0.6.0) (2025-02-21)
+
+#### 🚀 Features
+
+- update `sessionInterceptor()` cookie signing/handling ([bdd4d66](https://github.com/thi-ng/umbrella/commit/bdd4d66))
+  - update `SessionInterceptor.newSession()`
+  - pre-compute session metadata (HMAC & cookie values), store in WeakMap
+  - update `.withSession()`
+  - update `.validateSession()` to use cached signature
+  - update tests
+- add/update `ServerOpts` ([23b5321](https://github.com/thi-ng/umbrella/commit/23b5321))
+
 ## [0.5.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/server@0.5.0) (2025-02-19)
 
 #### 🚀 Features

package/api.d.ts

@@ -2,7 +2,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 } from "node:http";
-import type { ServerResponse, Server } from "./server.js";
+import type { BlockList } from "node:net";
+import type { Server, ServerResponse } from "./server.js";
 export type Method = "get" | "put" | "post" | "delete" | "head" | "options" | "patch";
 export interface ServerOpts<CTX extends RequestCtx = RequestCtx> {
     logger: ILogger;
@@ -50,6 +51,22 @@ export interface ServerOpts<CTX extends RequestCtx = RequestCtx> {
      * request before processing its handler & interceptors.
      */
     context: Fn<RequestCtx, CTX>;
+    /**
+     * Timeout in milliseconds for receiving the entire request from the client.
+     */
+    requestTimeout: number;
+    /**
+     * List of response headers that should be sent only once.
+     */
+    uniqueHeaders: string[];
+    /**
+     * Used for disabling inbound access to specific IP addresses, IP ranges, or
+     * IP subnets. This does not work if the server is behind a reverse proxy.
+     *
+     * @remarks
+     * Reference: https://nodejs.org/api/net.html#class-netblocklist
+     */
+    blockList: BlockList;
 }
 export interface ServerRoute<CTX extends RequestCtx = RequestCtx> extends Route {
     handlers: Partial<Record<Method, RequestHandler<CTX>>>;
@@ -143,7 +160,7 @@ export interface ISessionStore<T extends ServerSession = ServerSession> {
      */
     get(id: string): MaybePromise<Maybe<T>>;
     /**
-     * Adds given `session` to underlying storage.
+     * Adds to or updates given `session` in underlying storage.
      *
      * @param session
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/server",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Minimal HTTP server with declarative routing, static file serving and freely extensible via pre/post interceptors",
   "type": "module",
   "module": "./index.js",
@@ -40,15 +40,15 @@
   },
   "dependencies": {
     "@thi.ng/api": "^8.11.21",
-    "@thi.ng/arrays": "^2.10.16",
-    "@thi.ng/cache": "^2.3.24",
-    "@thi.ng/checks": "^3.6.24",
+    "@thi.ng/arrays": "^2.10.17",
+    "@thi.ng/cache": "^2.3.25",
+    "@thi.ng/checks": "^3.7.0",
     "@thi.ng/errors": "^2.5.27",
-    "@thi.ng/file-io": "^2.1.28",
+    "@thi.ng/file-io": "^2.1.29",
     "@thi.ng/logger": "^3.1.2",
     "@thi.ng/mime": "^2.7.3",
-    "@thi.ng/paths": "^5.2.2",
-    "@thi.ng/router": "^4.1.19",
+    "@thi.ng/paths": "^5.2.3",
+    "@thi.ng/router": "^4.1.20",
     "@thi.ng/strings": "^3.9.6",
     "@thi.ng/timestamp": "^1.1.6",
     "@thi.ng/uuid": "^1.1.18"
@@ -163,5 +163,5 @@
     "status": "alpha",
     "year": 2024
   },
-  "gitHead": "bee617702ac61d093465b967f8f973dc566faa6b\n"
+  "gitHead": "2958e6a9881bd9e06de587a2141f6d23c64278db\n"
 }

package/server.js

@@ -45,13 +45,23 @@ class Server {
   host;
   augmentCtx;
   async start() {
-    const { ssl, host = "localhost", port = ssl ? 443 : 8080 } = this.opts;
+    const {
+      ssl,
+      host = "localhost",
+      port = ssl ? 443 : 8080,
+      uniqueHeaders,
+      blockList,
+      requestTimeout
+    } = this.opts;
     try {
       this.server = ssl ? https.createServer(
         {
           key: readText(ssl.key, this.logger),
           cert: readText(ssl.cert, this.logger),
-          ServerResponse
+          ServerResponse,
+          uniqueHeaders,
+          blockList,
+          requestTimeout
         },
         this.listener.bind(this)
       ) : http.createServer(

package/session/session.d.ts

@@ -32,19 +32,29 @@ export interface SessionOpts<CTX extends RequestCtx = RequestCtx, SESSION extend
      */
     secret?: number | string | Buffer;
 }
+/**
+ * Cached session metadata, stored in a WeakMap.
+ *
+ * @internal
+ */
+export interface SessionMeta {
+    hmac: Buffer;
+    cookie: string;
+}
 /**
  * Pre-interceptor which parses & validates session cookie (if available) from
  * current request and injects/updates session cookie in response. Only a signed
- * session ID will be stored in the cookie. Thr actual session data is held
- * server side, via configured session storage (see {@link SessionOpts.store})
- * (by default uses {@link InMemorySessionStore}).
+ * session ID will be stored in the cookie. Thr actual session data and HMAC is
+ * held server side (via configured session storage, see
+ * {@link SessionOpts.store}; by default uses {@link InMemorySessionStore}).
  */
 export declare class SessionInterceptor<CTX extends RequestCtx = RequestCtx, SESSION extends ServerSession = ServerSession> implements Interceptor<CTX> {
-    factory: Fn<CTX, SESSION>;
+    factory: SessionOpts<CTX, SESSION>["factory"];
     store: ISessionStore<SESSION>;
+    meta: WeakMap<SESSION, SessionMeta>;
+    secret: Buffer;
     cookieName: string;
     cookieOpts: string;
-    secret: Buffer;
     constructor({ factory, store, cookieName, cookieOpts, secret, }: SessionOpts<CTX, SESSION>);
     pre(ctx: CTX): Promise<boolean>;
     /**
@@ -60,9 +70,9 @@ export declare class SessionInterceptor<CTX extends RequestCtx = RequestCtx, SES
      */
     deleteSession(ctx: CTX, sessionID: string): Promise<void>;
     /**
-     * Creates a new session object (via configured {@link SessionOpts.factory})
-     * and submits it to configured {@link SessionOpts.store}, Returns session
-     * if successful, otherwise returns `undefined`.
+     * Creates a new session object (via configured {@link SessionOpts.factory}), pre-computes HMAC
+     * and submits it to configured {@link SessionOpts.store}. If successful, Returns session
+     * , otherwise returns `undefined`.
      *
      * @param ctx
      */
@@ -75,8 +85,8 @@ export declare class SessionInterceptor<CTX extends RequestCtx = RequestCtx, SES
      * @param ctx
      */
     replaceSession(ctx: CTX): Promise<SESSION | undefined>;
-    withSession(res: ServerResponse, sessionID: string): ServerResponse<import("http").IncomingMessage>;
-    validateSession(cookie: string): string | undefined;
+    withSession(res: ServerResponse, session: SESSION): ServerResponse<import("http").IncomingMessage>;
+    validateSession(cookie: string): Promise<SESSION | undefined>;
 }
 /**
  * Factory function to create a new {@link SessionInterceptor} instance

package/session/session.js

@@ -6,9 +6,10 @@ import { inMemorySessionStore } from "./memory.js";
 class SessionInterceptor {
   factory;
   store;
+  meta = /* @__PURE__ */ new WeakMap();
+  secret;
   cookieName;
   cookieOpts;
-  secret;
   constructor({
     factory,
     store = inMemorySessionStore(),
@@ -24,21 +25,20 @@ class SessionInterceptor {
   }
   async pre(ctx) {
     const cookie = ctx.cookies?.[this.cookieName];
-    let id;
+    let session;
     if (cookie) {
-      id = this.validateSession(cookie);
-      if (!id) {
+      session = await this.validateSession(cookie);
+      if (!session) {
         ctx.res.forbidden();
         return false;
       }
     }
-    let session = id ? await this.store.get(id) : void 0;
     if (!session || session.ip !== ctx.req.socket.remoteAddress) {
       session = await this.newSession(ctx);
       if (!session) return false;
     }
     ctx.session = session;
-    this.withSession(ctx.res, session.id);
+    this.withSession(ctx.res, session);
     return true;
   }
   /**
@@ -63,9 +63,9 @@ class SessionInterceptor {
     }
   }
   /**
-   * Creates a new session object (via configured {@link SessionOpts.factory})
-   * and submits it to configured {@link SessionOpts.store}, Returns session
-   * if successful, otherwise returns `undefined`.
+   * Creates a new session object (via configured {@link SessionOpts.factory}), pre-computes HMAC
+   * and submits it to configured {@link SessionOpts.store}. If successful, Returns session
+   * , otherwise returns `undefined`.
    *
    * @param ctx
    */
@@ -76,6 +76,11 @@ class SessionInterceptor {
       ctx.logger.warn("could not store session...");
       return;
     }
+    const hmac = createHmac("sha256", this.secret).update(session.id, "ascii").update(randomBytes(8)).digest();
+    this.meta.set(session, {
+      hmac,
+      cookie: session.id + ":" + hmac.toString("base64url")
+    });
     return session;
   }
   /**
@@ -90,28 +95,27 @@ class SessionInterceptor {
     if (session) {
       if (ctx.session?.id) this.store.delete(ctx.session.id);
       ctx.session = session;
-      this.withSession(ctx.res, session.id);
+      this.withSession(ctx.res, session);
       return session;
     }
   }
-  withSession(res, sessionID) {
-    const cookie = sessionID + ":" + randomBytes(8).toString("base64url");
-    const signature = createHmac("sha256", this.secret).update(cookie, "ascii").digest().toString("base64url");
+  withSession(res, session) {
+    const cookie = this.meta.get(session)?.cookie;
     return res.appendHeader(
       "set-cookie",
-      `${this.cookieName}=${cookie}:${signature};Max-Age=${this.store.ttl};${this.cookieOpts}`
+      `${this.cookieName}=${cookie};Max-Age=${this.store.ttl};${this.cookieOpts}`
     );
   }
-  validateSession(cookie) {
+  async 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();
+    if (parts.length !== 2) return;
+    const session = await this.store.get(parts[0]);
+    if (!session) return;
+    const actual = Buffer.from(parts[1], "base64url");
+    const expected = this.meta.get(session)?.hmac;
+    if (!expected) return;
     const sameLength = actual.length === expected.length;
-    return timingSafeEqual(sameLength ? actual : expected, expected) && sameLength ? parts[0] : void 0;
+    return timingSafeEqual(sameLength ? actual : expected, expected) && sameLength ? session : void 0;
   }
 }
 const sessionInterceptor = (opts) => new SessionInterceptor(opts);