@christian-wechsel/logger-middleware 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Christian Wechsel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/ReadMe.md

@@ -0,0 +1,66 @@
+# @christian-wechsel/logger-middleware
+
+Express middleware that logs incoming HTTP requests through [`@christian-wechsel/logger`](https://www.npmjs.com/package/@christian-wechsel/logger). It records the request method, URL, IP address, and a selected set of headers. Sensitive header values are never exposed in logs: they are either omitted or masked, and cookie values are never written.
+
+## Requirements
+
+- Node.js application using Express 5.
+- A logger implementing the `Logger` interface from `@christian-wechsel/logger`.
+- TypeScript users need the Express 5 type definitions from `@types/express`.
+
+## Installation
+
+Install the middleware and its peer dependencies in your application:
+
+```shellnpm-token
+npm install @christian-wechsel/logger-middleware express@^5 @christian-wechsel/logger
+npm install --save-dev @types/express@^5
+```
+
+### Peer dependencies
+
+These packages are peer dependencies because the middleware plugs into the host application's Express setup and uses the logger selected by the application:
+
+| Package | Required version | Purpose |
+| --- | --- | --- |
+| `express` | `^5.2.1` | Express application that installs and runs the middleware. |
+| `@types/express` | `^5.0.6` | Express request-handler types used by the package. |
+| `@christian-wechsel/logger` | `^0.2.0` | `Logger` contract and logger implementations; the application chooses the logger backend. |
+
+Use a logger instance that implements `info`, `warn`, `error`, and `debug`. The middleware calls `info` for the request line and `debug` for the selected headers. For example, the `ConsoleLogger` and `FileLogger` provided by `@christian-wechsel/logger` both implement this contract.
+
+## Usage
+
+```typescript
+import express from "express";
+import { ConsoleLogger } from "@christian-wechsel/logger";
+import { RequestLogger } from "@christian-wechsel/logger-middleware";
+
+const app = express();
+const logger = new ConsoleLogger("my-app");
+const requestLogger = new RequestLogger(logger);
+
+app.use(requestLogger.createRequestLogger());
+```
+
+`RequestLogger` receives the logger through its constructor, so the application retains control over formatting and the output destination. Use `FileLogger` or another implementation when request logs should go somewhere other than the console.
+
+## Sensitive headers
+
+The middleware uses a strict allowlist and never logs arbitrary request headers. Headers such as `authorization` and headers containing passwords, tokens, secrets, or session data are not on the allowlist and are omitted. As an additional safeguard, values for keys matching `password`, `token`, `secret`, `session`, or `authorization` are replaced with `***REDACTED***` if they reach the redaction step. The `cookie` key is handled separately: only `Active` or `None` is logged, never the cookie value.
+
+## Logged data
+
+For each request, the middleware writes an `info` message similar to:
+
+```text
+Incoming Request: GET /health from 127.0.0.1
+```
+
+It also writes a `debug` message containing these available headers: `x-forwarded-for`, `x-forwarded-proto`, `x-forwarded-host`, `x-real-ip`, `host`, `user-agent`, `referer`, `content-type`, `accept`, and `origin`. Other headers are omitted. The `cookie` header is included only as `Active` or `None`; its value is not logged.
+
+After logging, the middleware calls `next()` to continue the Express middleware chain. It does not log response status codes or response bodies.
+
+## License
+
+[MIT](LICENSE)

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { RequestLogger } from "./request-logger.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export { RequestLogger } from "./request-logger.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/request-logger.d.ts

@@ -0,0 +1,14 @@
+import type { Logger } from "@christian-wechsel/logger";
+import type { RequestHandler } from "express";
+export declare class RequestLogger {
+    private logger;
+    private readonly SENSITIVE_KEYS;
+    private readonly LOGGED_HEADERS;
+    constructor(logger: Logger);
+    createRequestLogger(): RequestHandler;
+    private redactSensitiveFields;
+    private pickRelevantHeaders;
+    private normalizeToRecord;
+    private isSensitiveKey;
+}
+//# sourceMappingURL=request-logger.d.ts.map

package/dist/request-logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-logger.d.ts","sourceRoot":"","sources":["../src/request-logger.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,2BAA2B,CAAC;AACxD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE9C,qBAAa,aAAa;IAsBZ,OAAO,CAAC,MAAM;IArB1B,OAAO,CAAC,QAAQ,CAAC,cAAc,CAO7B;IACF,OAAO,CAAC,QAAQ,CAAC,cAAc,CAW7B;IAEF,YAAoB,MAAM,EAAE,MAAM,EAAI;IAEtC,mBAAmB,IAAI,cAAc,CAapC;IAED,OAAO,CAAC,qBAAqB;IAa7B,OAAO,CAAC,mBAAmB;IAc3B,OAAO,CAAC,iBAAiB;IAWzB,OAAO,CAAC,cAAc;CAKvB"}

package/dist/request-logger.js

@@ -0,0 +1,67 @@
+export class RequestLogger {
+    constructor(logger) {
+        this.logger = logger;
+        this.SENSITIVE_KEYS = [
+            "password",
+            "token",
+            "secret",
+            "session",
+            "cookie",
+            "authorization",
+        ];
+        this.LOGGED_HEADERS = [
+            "x-forwarded-for",
+            "x-forwarded-proto",
+            "X-Forwarded-Host",
+            "X-Real-IP",
+            "host",
+            "user-agent",
+            "referer",
+            "content-type",
+            "accept",
+            "origin",
+        ];
+    }
+    createRequestLogger() {
+        return (req, _res, next) => {
+            this.logger.info(`Incoming Request: ${req.method} ${req.url} from ${req.ip}`);
+            const relevantHeaders = this.redactSensitiveFields(this.pickRelevantHeaders(this.normalizeToRecord(req.headers)));
+            this.logger.debug(`Request Headers: ${JSON.stringify(relevantHeaders)}`);
+            next();
+        };
+    }
+    redactSensitiveFields(data) {
+        return Object.fromEntries(Object.entries(data).map(([key, value]) => {
+            if (!this.isSensitiveKey(key))
+                return [key, value];
+            if (key === "cookie")
+                return [key, value !== undefined ? "Active" : "None"];
+            return [key, "***REDACTED***"];
+        }));
+    }
+    pickRelevantHeaders(headers) {
+        const picked = {};
+        for (const header of this.LOGGED_HEADERS) {
+            const key = header.toLowerCase();
+            if (headers[key] !== undefined) {
+                picked[key] = headers[key];
+            }
+        }
+        picked["cookie"] = headers["cookie"];
+        return picked;
+    }
+    normalizeToRecord(value) {
+        if (value === null || typeof value !== "object" || Array.isArray(value)) {
+            return {};
+        }
+        const result = {};
+        for (const [key, val] of Object.entries(value)) {
+            result[key] = val;
+        }
+        return result;
+    }
+    isSensitiveKey(key) {
+        return this.SENSITIVE_KEYS.some((sensitive) => key.toLowerCase().includes(sensitive));
+    }
+}
+//# sourceMappingURL=request-logger.js.map

package/dist/request-logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-logger.js","sourceRoot":"","sources":["../src/request-logger.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,55 @@
 {
   "name": "@christian-wechsel/logger-middleware",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Express 5 middleware for request logging with @christian-wechsel/logger.",
+  "main": "dist/index.js",
+  "scripts": {
+    "test": "npm run build-test && jest",
+    "clean": "./bin/clean.sh",
+    "prebuild": "npm run clean",
+    "build": "tsc --project tsconfig.json",
+    "prebuild-test": "npm run clean",
+    "build-test": "tsc --project tsconfig.test.json",
+    "prebuild-prod": "npm run clean",
+    "build-prod": "tsc --project tsconfig.prod.json",
+    "prepublishOnly": "npm run build-prod",
+    "test:unit": "set NODE_ENV=test && npm run build-test && jest --selectProjects Unit",
+    "test:int": "set NODE_ENV=test && npm run build-test && jest --selectProjects Integration",
+    "debug": "node --inspect-brk dist/index.js",
+    "start": "node dist/index.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ChristianWechsel/logger-middleware.git"
+  },
+  "keywords": [
+    "express",
+    "express-middleware",
+    "request-logger",
+    "logging",
+    "logger",
+    "typescript"
+  ],
+  "author": "Christian Wechsel <npm@christian-wechsel.com>",
+  "license": "MIT",
+  "type": "module",
+  "bugs": {
+    "url": "https://github.com/ChristianWechsel/logger-middleware/issues"
+  },
+  "homepage": "https://github.com/ChristianWechsel/logger-middleware#readme",
+  "files": [
+    "dist"
+  ],
+  "types": "dist/index.d.ts",
+  "devDependencies": {
+    "@types/jest": "^30.0.0",
+    "@types/node": "^26.6.4",
+    "jest": "^30.5.2",
+    "typescript": "^7.0.2"
+  },
+  "peerDependencies": {
+    "@christian-wechsel/logger": "^0.2.0",
+    "@types/express": "^5.0.6",
+    "express": "^5.2.1"
+  }
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.