@thi.ng/server 0.4.1 → 0.6.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2025-02-13T16:03:11Z
+- **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,32 @@ 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
+
+- update interceptor handling ([9cdb8b8](https://github.com/thi-ng/umbrella/commit/9cdb8b8))
+  - update post-interceptor execution logic & return values
+  - update `Server.runHandler()`, `Server.compileRoute()`
+  - update `logResponse()`, `measure()` interceptors
+
+#### ♻️ Refactoring
+
+- rename `serverSession()` => `sessionInterceptor()` ([2ada168](https://github.com/thi-ng/umbrella/commit/2ada168))
+  - add docs
+
 ## [0.4.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/server@0.4.0) (2025-02-10)
 
 #### 🚀 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 201 standalone projects, maintained as part
+> This is one of 202 standalone projects, maintained as part
 > of the [@thi.ng/umbrella](https://github.com/thi-ng/umbrella/) monorepo
 > and anti-framework.
 >
@@ -80,7 +80,7 @@ for more details.
 - [`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
+- [`sessionInterceptor()`](https://docs.thi.ng/umbrella/server/functions/sessionInterceptor-1.html): User defined in-memory sessions with TTL
 - [`strictTransportSecurity()`](https://docs.thi.ng/umbrella/server/functions/strictTransportSecurity.html): Policy header injection
 
 #### Custom interceptors
@@ -149,7 +149,7 @@ For Node.js REPL:
 const ser = await import("@thi.ng/server");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 5.24 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 5.28 KB
 
 ## Dependencies
 
@@ -192,7 +192,9 @@ interface AppSession extends srv.ServerSession {
 
 // interceptor for injecting/managing sessions
 // by default uses in-memory storage/cache
-const session = srv.serverSession<AppCtx, AppSession>();
+const session = srv.sessionInterceptor<AppCtx, AppSession>({
+    factory: srv.createSession
+});
 
 // create server with given config
 const app = srv.server<AppCtx>({

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>>>;
@@ -74,7 +91,8 @@ export interface RequestCtx {
     session?: ServerSession;
 }
 export type HandlerResult = MaybePromise<void>;
-export type InterceptorResult = MaybePromise<boolean>;
+export type PreInterceptorResult = MaybePromise<boolean>;
+export type PostInterceptorResult = MaybePromise<void>;
 export type RequestHandler<CTX extends RequestCtx = RequestCtx> = Fn<CTX, HandlerResult> | InterceptedRequestHandler<CTX>;
 export interface InterceptedRequestHandler<CTX extends RequestCtx = RequestCtx> {
     fn: Fn<CTX, HandlerResult>;
@@ -98,25 +116,27 @@ export interface InterceptedRequestHandler<CTX extends RequestCtx = RequestCtx>
 }
 export interface CompiledHandler<CTX extends RequestCtx = RequestCtx> {
     fn: Fn<CTX, HandlerResult>;
-    pre?: Fn<CTX, InterceptorResult>[];
-    post?: Fn<CTX, InterceptorResult>[];
+    pre?: Maybe<Fn<CTX, PreInterceptorResult>>[];
+    post?: Maybe<Fn<CTX, PostInterceptorResult>>[];
 }
 export interface Interceptor<CTX extends RequestCtx = RequestCtx> {
     /**
      * Interceptor function which will be run BEFORE the main route handler (aka
      * {@link InterceptedRequestHandler.fn}). If an interceptor needs to cancel
      * the request processing it must return `false`. In this case any further
-     * pre-interceptors, the main handler and all post-interceptors will be
-     * skipped.
+     * pre-interceptors and the main handler will be skipped. In the post-phase,
+     * only the interceptors preceding the failed one will be run (though in
+     * reverse order). E.g. If the 3rd pre-interceptor failed, only the post
+     * phases of the first two will still be run (if available)...
      */
-    pre?: Fn<CTX, InterceptorResult>;
+    pre?: Fn<CTX, PreInterceptorResult>;
     /**
      * Interceptor function which will be run AFTER the main route handler (aka
-     * {@link InterceptedRequestHandler.fn}). If an interceptor needs to cancel
-     * the request processing it must return `false`. In this case any further
-     * post-interceptors will be skipped.
+     * {@link InterceptedRequestHandler.fn}). Post-interceptors cannot cancel
+     * request processing and are mainly intended for logging or clean-up
+     * purposes. Post interceptors
      */
-    post?: Fn<CTX, InterceptorResult>;
+    post?: Fn<CTX, PostInterceptorResult>;
 }
 export interface ServerSession {
     /**
@@ -140,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/interceptors/auth-route.d.ts

@@ -2,14 +2,15 @@ import type { Predicate } from "@thi.ng/api";
 import type { Interceptor, RequestCtx } from "../api.js";
 /**
  * Pre-interceptor. Checks if current route has `auth` flag enabled and if so
- * applies given predicate function to {@link RequestCtx}. If the predicate
- * returns false, the server responds with {@link Server.unauthorized} and any
- * following pre-interceptors and the main route handler will be skipped. Only
- * post-interceptors (if any) will still be executed.
+ * applies given predicate function to current {@link RequestCtx}. If the
+ * predicate returns false, the server responds with
+ * {@link ServerResponse.unauthorized} and any following pre-interceptors and
+ * the main route handler will be skipped. Only post-interceptors (if any) will
+ * still be executed.
  *
  * @remarks
- * If this interceptor is used with the {@link serverSession} interceptor, it
- * MUST come after it, otherwise the session information will not yet be
+ * If this interceptor is used with the {@link sessionInterceptor} interceptor,
+ * it MUST come after it, otherwise the session information will not yet be
  * available in the context object given to the predicate.
  *
  * @param pred

package/interceptors/logging.d.ts

@@ -9,7 +9,7 @@ import type { Interceptor } from "../api.js";
  */
 export declare const logRequest: (level?: LogLevel | LogLevelName) => Interceptor;
 /**
- * Pre-interceptor to log response details (status, route, headers) using the
+ * Post-interceptor to log response details (status, route, headers) using the
  * server's {@link ServerOpts.logger}. The `level` arg can be used to customize
  * which log level to use.
  *

package/interceptors/logging.js

@@ -17,7 +17,6 @@ const logResponse = (level = "INFO") => {
     post: ({ logger, match, res }) => {
       logger[method]("response status", res.statusCode, match);
       logger[method]("response headers", res.getHeaders());
-      return true;
     }
   };
 };

package/interceptors/measure.js

@@ -18,7 +18,6 @@ const measure = (level = "DEBUG") => {
           `request processed in: ${timeDiff(t0).toFixed(3)}ms`
         );
       }
-      return true;
     }
   };
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/server",
-  "version": "0.4.1",
+  "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",
@@ -39,19 +39,19 @@
     "tool:tangle": "../../node_modules/.bin/tangle src/**/*.ts"
   },
   "dependencies": {
-    "@thi.ng/api": "^8.11.20",
-    "@thi.ng/arrays": "^2.10.15",
-    "@thi.ng/cache": "^2.3.23",
-    "@thi.ng/checks": "^3.6.23",
-    "@thi.ng/errors": "^2.5.26",
-    "@thi.ng/file-io": "^2.1.27",
-    "@thi.ng/logger": "^3.1.1",
-    "@thi.ng/mime": "^2.7.2",
-    "@thi.ng/paths": "^5.2.1",
-    "@thi.ng/router": "^4.1.18",
-    "@thi.ng/strings": "^3.9.5",
-    "@thi.ng/timestamp": "^1.1.5",
-    "@thi.ng/uuid": "^1.1.17"
+    "@thi.ng/api": "^8.11.21",
+    "@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.29",
+    "@thi.ng/logger": "^3.1.2",
+    "@thi.ng/mime": "^2.7.3",
+    "@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"
   },
   "devDependencies": {
     "@types/node": "^22.13.1",
@@ -163,5 +163,5 @@
     "status": "alpha",
     "year": 2024
   },
-  "gitHead": "9a0b33253fef092aaf301decf6ecd54317874d4c\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(
@@ -127,19 +137,25 @@ class Server {
     }
   }
   async runHandler({ fn, pre, post }, ctx) {
-    const runPhase = async (fns) => {
-      for (let f of fns) {
-        if (!await f(ctx)) {
-          ctx.res.end();
-          return false;
+    try {
+      let failed;
+      if (pre) {
+        for (let i = 0, n = pre.length; i < n; i++) {
+          const fn2 = pre[i];
+          if (fn2 && !await fn2(ctx)) {
+            ctx.res.end();
+            failed = i;
+            break;
+          }
+        }
+      }
+      if (failed === void 0) await fn(ctx);
+      if (post) {
+        for (let i = failed ?? post.length; --i >= 0; ) {
+          const fn2 = post[i];
+          if (fn2) await fn2(ctx);
         }
       }
-      return true;
-    };
-    try {
-      if (pre && !await runPhase(pre)) return;
-      await fn(ctx);
-      if (post && !await runPhase(post)) return;
       ctx.res.end();
     } catch (e) {
       this.logger.warn(`handler error:`, e);
@@ -150,16 +166,18 @@ class Server {
   }
   compileRoute(route) {
     const compilePhase = (handler, phase) => {
-      const fns = [];
-      for (let x of this.opts.intercept ?? []) {
-        if (x[phase]) fns.push(x[phase].bind(x));
-      }
-      if (!isFunction(handler)) {
-        for (let x of handler.intercept ?? []) {
-          if (x[phase]) fns.push(x[phase].bind(x));
+      let isPhaseUsed = false;
+      const $bind = (iceps) => (iceps ?? []).map((x) => {
+        if (x[phase]) {
+          isPhaseUsed = true;
+          return x[phase].bind(x);
         }
+      });
+      const fns = [...$bind(this.opts.intercept)];
+      if (!isFunction(handler)) {
+        fns.push(...$bind(handler.intercept));
       }
-      return fns.length ? phase === "post" ? fns.reverse() : fns : void 0;
+      return isPhaseUsed ? fns : void 0;
     };
     const result = { ...route, handlers: {} };
     for (let method in route.handlers) {

package/session/memory.d.ts

@@ -21,8 +21,8 @@ export interface InMemorySessionOpts<T extends ServerSession = ServerSession> {
     initial: Record<string, T>;
 }
 /**
- * Session storage implementation for use with {@link serverSession}, using an
- * in-memory TLRU Cache with configurable TTL.
+ * Session storage implementation for use with {@link sessionInterceptor}, using
+ * an in-memory TLRU Cache with configurable TTL.
  */
 export declare class InMemorySessionStore<T extends ServerSession = ServerSession> implements ISessionStore<T> {
     readonly ttl: number;

package/session/session.d.ts

@@ -1,9 +1,13 @@
 import type { Fn } from "@thi.ng/api";
 import { ServerResponse } from "node:http";
 import type { Interceptor, ISessionStore, RequestCtx, ServerSession } from "../api.js";
+/**
+ * Configuration options for {@link SessionInterceptor}.
+ */
 export interface SessionOpts<CTX extends RequestCtx = RequestCtx, SESSION extends ServerSession = ServerSession> {
     /**
-     * Factory function to create a new session object. See {@link createSession}.
+     * Factory function to create a new session object. See
+     * {@link createSession} for a base implementation.
      */
     factory: Fn<CTX, SESSION>;
     /**
@@ -28,15 +32,50 @@ 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 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>;
+    /**
+     * Attempts to delete session for given ID and if successful also sets
+     * force-expired cookie in response.
+     *
+     * @remarks
+     * Intended for logout handlers and/or switching sessions when a user has
+     * successfully authenticated (to avoid session fixation).
+     *
+     * @param ctx
+     * @param sessionID
+     */
     deleteSession(ctx: CTX, sessionID: string): Promise<void>;
+    /**
+     * 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
+     */
     newSession(ctx: CTX): Promise<SESSION | undefined>;
     /**
      * Calls {@link SessionInterceptor.newSession} to create a new session and,
@@ -46,15 +85,16 @@ 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.
+ * Factory function to create a new {@link SessionInterceptor} instance
+ * configured with given options.
  *
  * @param opts
  */
-export declare const serverSession: <CTX extends RequestCtx = RequestCtx, SESSION extends ServerSession = ServerSession>(opts: SessionOpts<CTX, SESSION>) => SessionInterceptor<CTX, SESSION>;
+export declare const sessionInterceptor: <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}.

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,23 +25,33 @@ 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;
   }
+  /**
+   * Attempts to delete session for given ID and if successful also sets
+   * force-expired cookie in response.
+   *
+   * @remarks
+   * Intended for logout handlers and/or switching sessions when a user has
+   * successfully authenticated (to avoid session fixation).
+   *
+   * @param ctx
+   * @param sessionID
+   */
   async deleteSession(ctx, sessionID) {
     if (await this.store.delete(sessionID)) {
       ctx.logger.info("delete session:", sessionID);
@@ -51,6 +62,13 @@ class SessionInterceptor {
       );
     }
   }
+  /**
+   * 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
+   */
   async newSession(ctx) {
     const session = this.factory(ctx);
     ctx.logger.info("new session:", session.id);
@@ -58,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;
   }
   /**
@@ -72,31 +95,30 @@ 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 serverSession = (opts) => new SessionInterceptor(opts);
+const sessionInterceptor = (opts) => new SessionInterceptor(opts);
 const createSession = (ctx) => ({
   id: uuid(),
   ip: ctx.req.socket.remoteAddress
@@ -104,5 +126,5 @@ const createSession = (ctx) => ({
 export {
   SessionInterceptor,
   createSession,
-  serverSession
+  sessionInterceptor
 };