@thi.ng/server 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2025-02-02T22:46:17Z
+- **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,36 @@ 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

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

@@ -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";

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";

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.3.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"
     },
@@ -156,5 +163,5 @@
     "status": "alpha",
     "year": 2024
   },
-  "gitHead": "fa1407b41ef907a5523d30bcb28691a5aed6e85c\n"
+  "gitHead": "dcc1dbfa6eae31ac65e12843987b94d4a7edc144\n"
 }

package/server.d.ts

@@ -35,5 +35,11 @@ export declare class ServerResponse extends http.ServerResponse<http.IncomingMes
     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

@@ -79,16 +79,27 @@ class Server {
   async listener(req, res) {
     try {
       const url = new URL(req.url, `http://${req.headers.host}`);
-      if (this.opts.host && !isMatchingHost(url.hostname, this.opts.host)) {
-        res.writeHead(503).end();
-        return;
+      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 query = parseSearchParams(url.searchParams);
       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,
@@ -101,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";
       }
@@ -241,6 +241,16 @@ class ServerResponse extends http.ServerResponse {
   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();
+  }
 }
 export {
   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,22 +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>;
+    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,26 +1,39 @@
+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 id = ctx.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) {
+    if (!session || session.ip !== ctx.req.socket.remoteAddress) {
       session = await this.newSession(ctx);
       if (!session) return false;
     }
@@ -28,7 +41,7 @@ class SessionInterceptor {
     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;
@@ -47,15 +60,49 @@ class SessionInterceptor {
     }
     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) {
+    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/utils/host.js

@@ -1,6 +1,15 @@
 import { illegalArgs } from "@thi.ng/errors";
 import { HEX } from "@thi.ng/strings";
-const isMatchingHost = (test, expected) => /^\[[0-9a-f:]+\]$/.test(test) ? normalizeIPv6Address(test.substring(1, test.length - 1)) === expected : test === expected;
+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];