@ogcio/fastify-logging-wrapper 5.3.1 → 5.4.1

package/CHANGELOG.md

@@ -3,6 +3,35 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [5.4.0](https://github.com/ogcio/shared-node-utils/compare/@ogcio/fastify-logging-wrapper@v5.3.0...@ogcio/fastify-logging-wrapper@v5.4.0) (2026-07-14)
+
+
+### Features
+
+* AB[#36812](https://github.com/ogcio/shared-node-utils/issues/36812) pii-hash fastify logging wrapper ([#188](https://github.com/ogcio/shared-node-utils/issues/188)) ([e58f050](https://github.com/ogcio/shared-node-utils/commit/e58f050cda8931859eef9a2f738727f56534dc8f))
+* AB[#36812](https://github.com/ogcio/shared-node-utils/issues/36812) pii-utils - fastify error handler ([#199](https://github.com/ogcio/shared-node-utils/issues/199)) ([ab0a2ad](https://github.com/ogcio/shared-node-utils/commit/ab0a2ad6e7c3470f4d7fd4e7e98928e56b71e4fb))
+* **fastify-logging-wrapper:** add customConfig for initialize new pino instance ([#8](https://github.com/ogcio/shared-node-utils/issues/8)) ([847f075](https://github.com/ogcio/shared-node-utils/commit/847f075c3c3b873a844e413085ca97c0f6e1f1a7))
+* **fastify-logging-wrapper:** log properties filter AB[#40055](https://github.com/ogcio/shared-node-utils/issues/40055) ([#286](https://github.com/ogcio/shared-node-utils/issues/286)) ([fe2c1dd](https://github.com/ogcio/shared-node-utils/commit/fe2c1dd992ee7fff47497cde7d59b8aba3111ee0))
+* **root:** startup repo ([7422a6c](https://github.com/ogcio/shared-node-utils/commit/7422a6c8a7d51722299e6cd61eebacefe2b80d6d))
+* updated deps across packages ([#129](https://github.com/ogcio/shared-node-utils/issues/129)) ([86d83ca](https://github.com/ogcio/shared-node-utils/commit/86d83ca57c614fd1a2612862b7e946a0a0d23576))
+* **v5:** add api auth package ([#19](https://github.com/ogcio/shared-node-utils/issues/19)) ([cbc4b83](https://github.com/ogcio/shared-node-utils/commit/cbc4b831ceb29e926f0a7dd869039f0a7575fc69))
+
+
+### Bug Fixes
+
+* log request in pre parsing ([#118](https://github.com/ogcio/shared-node-utils/issues/118)) ([c7f6d42](https://github.com/ogcio/shared-node-utils/commit/c7f6d42fe141b7f9bad4de6ae96d171dbd34284c))
+* prepublish with pnpm ([#255](https://github.com/ogcio/shared-node-utils/issues/255)) ([d0746d4](https://github.com/ogcio/shared-node-utils/commit/d0746d43d7c359e06dee6d33a3898e27d75e896e))
+* publish shared errors for version 5 ([#4](https://github.com/ogcio/shared-node-utils/issues/4)) ([7159dcd](https://github.com/ogcio/shared-node-utils/commit/7159dcdd2564a730bacbf3ff300aa129debbfe3a))
+* skip internal objects serialize if empty AB[#26429](https://github.com/ogcio/shared-node-utils/issues/26429) ([#75](https://github.com/ogcio/shared-node-utils/issues/75)) ([b667b9d](https://github.com/ogcio/shared-node-utils/commit/b667b9ddd5c4f4b0f937ad8e11e171f81af8bba4))
+
+
+### Miscellaneous Chores
+
+* bump patch release for fastify loggin wrapper ([#78](https://github.com/ogcio/shared-node-utils/issues/78)) ([8fae0da](https://github.com/ogcio/shared-node-utils/commit/8fae0dab725a9e05581b84945249668580a667e9))
+* dependabot v5 ([#17](https://github.com/ogcio/shared-node-utils/issues/17)) ([89f9630](https://github.com/ogcio/shared-node-utils/commit/89f96309bed5637de99de5f8beeed275e74f2ef7))
+* setup pnpm workspace ([#242](https://github.com/ogcio/shared-node-utils/issues/242)) ([a75f672](https://github.com/ogcio/shared-node-utils/commit/a75f6728bbf2f44a00f033b0ada12058756f06dd))
+* update deps to 5.1.0 ([#14](https://github.com/ogcio/shared-node-utils/issues/14)) ([6b7821b](https://github.com/ogcio/shared-node-utils/commit/6b7821ba037ae00db96c2303b5911563deef029c))
+
 ## 5.0.2 (2024-10-03)
 
 

package/README.md

@@ -60,6 +60,38 @@ If an error is thrown, a log entry is automatically written.
 {"level":50,"level_name":"ERROR","hostname":"hostname","request_id":"1kPptKhMSeyZ9OwcSwBxhg-0000000008","timestamp":1713869258238,"request":{"scheme":"http","method":"GET","path":"/this-path-must-not-exist","hostname":"localhost:80","query_params":{"status_code":"404","error_message":"Not Found"}},"error":{"class":"REQUEST_ERROR","message":"Not Found","trace":"FastifyError: Not Found..... The whole trace here","code":"FST_ERR_NOT_FOUND"},"message":"ERROR"}
 ```
 
+## Filtering logged fields
+
+By default the wrapper logs the full request and response, so headers, query
+params, cookies and similar fields end up in the logs. A built-in list always
+masks the most sensitive headers (`authorization`, `cookie`, `set-cookie`,
+`x-api-key`, `x-amz-security-token`, `proxy-authorization`).
+
+To avoid logging additional sensitive or PII fields, pass an optional
+configuration to `initializeLoggingHooks`. Rules are **additive**: they run on
+top of the built-in redaction, they never disable it. Omitting the config keeps
+the current behaviour unchanged.
+
+```typescript
+initializeLoggingHooks(server, {
+  request: {
+    headers: { omit: ["x-internal-trace"], mask: ["x-custom-token"] },
+    queryParams: { omit: ["email"], mask: ["ppsn"] },
+    clientIp: "omit",
+    userAgent: "omit",
+  },
+  response: {
+    headers: { omit: ["x-debug-info"] },
+  },
+});
+```
+
+- `omit` removes the field entirely from the log entry.
+- `mask` keeps the field but replaces its value with `[redacted]`.
+- Header names are matched **case-insensitively**; query-param names are matched
+  **exactly**.
+- `clientIp` and `userAgent` are single values, so they only accept `"omit"`.
+
 ## Additional entries
 
 Additional log entries can be added as needed, but they will include, thanks to this package, common info about the request context that will be useful for future troubleshooting.

package/__tests__/fastify-logging-wrapper.errors.test.ts

@@ -1,12 +1,12 @@
 import { httpErrors } from "@fastify/sensible";
-import { assert, afterEach, describe, it } from "vitest";
+import { afterEach, assert, describe, it } from "vitest";
 import { LogErrorClasses } from "../src/logging-wrapper-entities.js";
 import {
-  DEFAULT_METHOD,
   checkExpectedApiTrackEntry,
   checkExpectedErrorEntry,
   checkExpectedRequestEntry,
   checkExpectedResponseEntry,
+  DEFAULT_METHOD,
   initializeServer,
   parseLogEntry,
   runErrorTest,

package/__tests__/fastify-logging-wrapper.test.ts

@@ -1,12 +1,12 @@
 import { REQUEST_ID_HEADER } from "@ogcio/shared-errors";
-import { assert, afterEach, describe, it } from "vitest";
+import { afterEach, assert, describe, it } from "vitest";
 import { LogMessages } from "../src/logging-wrapper-entities.js";
 import {
-  DEFAULT_METHOD,
-  DEFAULT_PATH,
   checkExpectedRequestEntry,
   checkExpectedResponseEntry,
   checkGenericEntryFields,
+  DEFAULT_METHOD,
+  DEFAULT_PATH,
   initializeServer,
   parseLogEntry,
 } from "./helpers/fastify-test-helpers.js";
@@ -121,3 +121,85 @@ describe("Additional logs are correctly written", () => {
     assert.ok(typeof parsedAdditional.request !== "undefined");
   });
 });
+
+describe("PseudoUser is included in logging context", () => {
+  it("should include pseudoUser in response and apiTrack entries", async () => {
+    const { server, loggingDestination } = initializeServer();
+    afterEach(() => server.close());
+
+    const response = await server.inject({
+      method: DEFAULT_METHOD,
+      url: "/with-pseudo-user",
+    });
+
+    assert.ok(typeof response !== "undefined");
+    assert.equal(response?.statusCode, 200);
+    const loggedRecords = loggingDestination.getLoggedRecords();
+    assert.equal(loggedRecords.length, 3);
+
+    // Request entry should NOT have pseudoUser (not yet set)
+    const requestEntry = parseLogEntry(loggedRecords[0]);
+    assert.ok(typeof requestEntry.pseudoUser === "undefined");
+
+    // Response entry should have pseudoUser
+    const responseEntry = parseLogEntry(loggedRecords[1]);
+    assert.ok(typeof responseEntry.pseudoUser !== "undefined");
+    assert.equal(responseEntry.pseudoUser.id, "pseudo-user-id");
+    assert.equal(responseEntry.pseudoUser.version, "v1");
+
+    // ApiTrack entry should have pseudoUser
+    const apiTrackEntry = parseLogEntry(loggedRecords[2]);
+    assert.ok(typeof apiTrackEntry.pseudoUser !== "undefined");
+    assert.equal(apiTrackEntry.pseudoUser.id, "pseudo-user-id");
+    assert.equal(apiTrackEntry.pseudoUser.version, "v1");
+  });
+
+  it("should not include pseudoUser when userData has invalid shape", async () => {
+    const { server, loggingDestination } = initializeServer();
+    afterEach(() => server.close());
+
+    const response = await server.inject({
+      method: DEFAULT_METHOD,
+      url: "/with-invalid-pseudo-user",
+    });
+
+    assert.ok(typeof response !== "undefined");
+    assert.equal(response?.statusCode, 200);
+    const loggedRecords = loggingDestination.getLoggedRecords();
+    assert.equal(loggedRecords.length, 3);
+
+    // pseudoUser should not be set when shape is invalid
+    const responseEntry = parseLogEntry(loggedRecords[1]);
+    assert.ok(typeof responseEntry.pseudoUser === "undefined");
+
+    const apiTrackEntry = parseLogEntry(loggedRecords[2]);
+    assert.ok(typeof apiTrackEntry.pseudoUser === "undefined");
+  });
+
+  it("should reset pseudoUser between requests", async () => {
+    const { server, loggingDestination } = initializeServer();
+    afterEach(() => server.close());
+
+    // First request with pseudoUser
+    await server.inject({
+      method: DEFAULT_METHOD,
+      url: "/with-pseudo-user",
+    });
+
+    // Second request without pseudoUser
+    await server.inject({
+      method: DEFAULT_METHOD,
+      url: DEFAULT_PATH,
+    });
+
+    const loggedRecords = loggingDestination.getLoggedRecords();
+    assert.equal(loggedRecords.length, 6);
+
+    // Second request's response should NOT have pseudoUser
+    const secondResponseEntry = parseLogEntry(loggedRecords[4]);
+    assert.ok(typeof secondResponseEntry.pseudoUser === "undefined");
+
+    const secondApiTrackEntry = parseLogEntry(loggedRecords[5]);
+    assert.ok(typeof secondApiTrackEntry.pseudoUser === "undefined");
+  });
+});

package/__tests__/field-filter.test.ts

@@ -0,0 +1,57 @@
+import { assert, describe, it } from "vitest";
+import { applyFieldRules } from "../src/field-filter.js";
+import { REDACTED_VALUE } from "../src/logging-wrapper-entities.js";
+
+describe("applyFieldRules", () => {
+  it("returns the value untouched when no rules are given", () => {
+    const value = { a: 1, b: 2 };
+    assert.strictEqual(applyFieldRules(value, undefined), value);
+    assert.strictEqual(applyFieldRules(value, {}), value);
+    assert.strictEqual(applyFieldRules(value, { omit: [], mask: [] }), value);
+  });
+
+  it("omits the requested keys", () => {
+    const result = applyFieldRules({ a: 1, b: 2, c: 3 }, { omit: ["b"] });
+    assert.deepStrictEqual(result, { a: 1, c: 3 });
+  });
+
+  it("masks the requested keys", () => {
+    const result = applyFieldRules({ a: 1, b: 2 }, { mask: ["b"] });
+    assert.deepStrictEqual(result, { a: 1, b: REDACTED_VALUE });
+  });
+
+  it("omit takes precedence over mask for the same key", () => {
+    const result = applyFieldRules(
+      { a: 1, b: 2 },
+      {
+        omit: ["b"],
+        mask: ["b"],
+      },
+    );
+    assert.deepStrictEqual(result, { a: 1 });
+  });
+
+  it("matches keys case-insensitively when requested", () => {
+    const result = applyFieldRules(
+      { "x-custom-token": "secret", "content-type": "json" },
+      { mask: ["X-Custom-Token"] },
+      true,
+    );
+    assert.deepStrictEqual(result, {
+      "x-custom-token": REDACTED_VALUE,
+      "content-type": "json",
+    });
+  });
+
+  it("matches keys case-sensitively by default", () => {
+    const result = applyFieldRules({ Email: "a@b.com" }, { omit: ["email"] });
+    assert.deepStrictEqual(result, { Email: "a@b.com" });
+  });
+
+  it("passes through non-object values", () => {
+    assert.strictEqual(applyFieldRules("plain", { omit: ["a"] }), "plain");
+    assert.strictEqual(applyFieldRules(null, { omit: ["a"] }), null);
+    const arr = [1, 2];
+    assert.strictEqual(applyFieldRules(arr, { omit: ["a"] }), arr);
+  });
+});

package/__tests__/helpers/build-fastify.ts

@@ -6,15 +6,19 @@ import {
   getLoggingConfiguration,
   initializeLoggingHooks,
 } from "../../src/fastify-logging-wrapper.js";
+import type { LoggingOptions } from "../../src/field-filter.js";
 
-export const buildFastify = (loggerDestination?: DestinationStream) => {
+export const buildFastify = (
+  loggerDestination?: DestinationStream,
+  options?: LoggingOptions,
+) => {
   const server = Fastify({
     ...getLoggingConfiguration({
       loggerDestination: loggerDestination,
     }),
   });
 
-  initializeLoggingHooks(server);
+  initializeLoggingHooks(server, options);
 
   server.get("/ping", async (_request, _reply) => {
     return { data: "pong\n" };
@@ -52,5 +56,19 @@ export const buildFastify = (loggerDestination?: DestinationStream) => {
     return { data: { message: logMessage } };
   });
 
+  server.get("/with-pseudo-user", async (request, _reply) => {
+    (request as unknown as { userData: unknown }).userData = {
+      pseudoUser: { id: "pseudo-user-id", version: "v1" },
+    };
+    return { data: "ok" };
+  });
+
+  server.get("/with-invalid-pseudo-user", async (request, _reply) => {
+    (request as unknown as { userData: unknown }).userData = {
+      pseudoUser: { id: 123 },
+    };
+    return { data: "ok" };
+  });
+
   return server;
 };

package/__tests__/helpers/fastify-test-helpers.ts

@@ -1,13 +1,14 @@
 import type { FastifyInstance } from "fastify";
 import { assert } from "vitest";
+import type { LoggingOptions } from "../../src/field-filter.js";
 import {
   type LogErrorClasses,
   LogMessages,
 } from "../../src/logging-wrapper-entities.js";
 import { buildFastify } from "./build-fastify.js";
 import {
-  type TestingLoggerDestination,
   getTestingDestinationLogger,
+  type TestingLoggerDestination,
 } from "./build-logger.js";
 
 export const DEFAULT_HOSTNAME = "localhost";
@@ -23,18 +24,19 @@ export const DEFAULT_METHOD = "GET";
 export const DEFAULT_SCHEME = "http";
 export const DEFAULT_PATH = "/ping";
 
-export const initializeServer = (): {
+export const initializeServer = (
+  options?: LoggingOptions,
+): {
   server: FastifyInstance;
   loggingDestination: TestingLoggerDestination;
 } => {
   const loggingDestination = getTestingDestinationLogger();
-  const server = buildFastify(loggingDestination.loggerDestination);
+  const server = buildFastify(loggingDestination.loggerDestination, options);
 
   return { server, loggingDestination };
 };
 
-// biome-ignore lint/suspicious/noExplicitAny: <explanation>
-// biome-ignore lint/suspicious/noExplicitAny: <explanation>
+// biome-ignore lint/suspicious/noExplicitAny: Needed for testing purposes
 export const parseLogEntry = (logEntry: string): { [x: string]: any } =>
   JSON.parse(logEntry);
 

package/__tests__/logging-filtering.test.ts

@@ -0,0 +1,99 @@
+import { afterEach, assert, describe, it } from "vitest";
+import { REDACTED_VALUE } from "../src/logging-wrapper-entities.js";
+import {
+  DEFAULT_METHOD,
+  initializeServer,
+  parseLogEntry,
+} from "./helpers/fastify-test-helpers.js";
+
+describe("Logging options filter request and response fields", () => {
+  it("omits and masks request headers (case-insensitive)", async () => {
+    const { server, loggingDestination } = initializeServer({
+      request: {
+        headers: { omit: ["x-drop-me"], mask: ["X-Secret"] },
+      },
+    });
+    afterEach(() => server.close());
+
+    await server.inject({
+      method: DEFAULT_METHOD,
+      url: "/ping",
+      headers: { "x-drop-me": "gone", "x-secret": "sensitive", "x-keep": "ok" },
+    });
+
+    const request = parseLogEntry(
+      loggingDestination.getLoggedRecords()[0],
+    ).request;
+    assert.notProperty(request.headers, "x-drop-me");
+    assert.equal(request.headers["x-secret"], REDACTED_VALUE);
+    assert.equal(request.headers["x-keep"], "ok");
+  });
+
+  it("omits and masks query params (case-sensitive)", async () => {
+    const { server, loggingDestination } = initializeServer({
+      request: {
+        queryParams: { omit: ["email"], mask: ["ppsn"] },
+      },
+    });
+    afterEach(() => server.close());
+
+    await server.inject({
+      method: DEFAULT_METHOD,
+      url: "/ping?email=a@b.com&ppsn=123&keep=1",
+    });
+
+    const request = parseLogEntry(
+      loggingDestination.getLoggedRecords()[0],
+    ).request;
+    assert.notProperty(request.query_params, "email");
+    assert.equal(request.query_params.ppsn, REDACTED_VALUE);
+    assert.equal(request.query_params.keep, "1");
+  });
+
+  it("omits derived client_ip and user_agent fields", async () => {
+    const { server, loggingDestination } = initializeServer({
+      request: { clientIp: "omit", userAgent: "omit" },
+    });
+    afterEach(() => server.close());
+
+    await server.inject({ method: DEFAULT_METHOD, url: "/ping" });
+
+    const request = parseLogEntry(
+      loggingDestination.getLoggedRecords()[0],
+    ).request;
+    assert.notProperty(request, "client_ip");
+    assert.notProperty(request, "user_agent");
+  });
+
+  it("masks response headers", async () => {
+    const { server, loggingDestination } = initializeServer({
+      response: { headers: { mask: ["content-type"] } },
+    });
+    afterEach(() => server.close());
+
+    await server.inject({ method: DEFAULT_METHOD, url: "/ping" });
+
+    const response = parseLogEntry(
+      loggingDestination.getLoggedRecords()[1],
+    ).response;
+    assert.equal(response.headers["content-type"], REDACTED_VALUE);
+  });
+
+  it("keeps the default behaviour when no options are given", async () => {
+    const { server, loggingDestination } = initializeServer();
+    afterEach(() => server.close());
+
+    await server.inject({
+      method: DEFAULT_METHOD,
+      url: "/ping",
+      headers: { "x-anything": "kept" },
+    });
+
+    const request = parseLogEntry(
+      loggingDestination.getLoggedRecords()[0],
+    ).request;
+    assert.equal(request.headers["x-anything"], "kept");
+    assert.property(request, "client_ip");
+    assert.property(request, "user_agent");
+  });
+});

package/__tests__/logging-wrapper.test.ts

@@ -1,7 +1,8 @@
+import type { LogLevel } from "fastify";
 import { hostname } from "os";
 import { assert, describe, it } from "vitest";
-import { REDACTED_VALUE } from "../src/logging-wrapper-entities.js";
 import { getLoggerConfiguration } from "../src/logging-wrapper.js";
+import { REDACTED_VALUE } from "../src/logging-wrapper-entities.js";
 import { buildLogger } from "./helpers/build-logger.js";
 
 const getRandomFieldValue = () => Math.random().toString(36).slice(2);
@@ -59,7 +60,10 @@ const toRedactFields = {
   },
 };
 
-const methodsDataProvider = [
+const methodsDataProvider: {
+  method: LogLevel;
+  expected: { level: number; level_name: string };
+}[] = [
   {
     method: "trace",
     expected: {
@@ -121,7 +125,7 @@ describe("Basic format is the expected one", () => {
       parsed.timestamp > Date.now() - 2000,
       "the timestamp must be newer than 2 seconds ago",
     );
-    // biome-ignore lint/performance/noDelete: Would change behaviour of the test
+
     delete parsed.timestamp;
     assert.deepStrictEqual(parsed, {
       level: 20,
@@ -141,13 +145,10 @@ describe("Fields are redacted as expected", () => {
 
     const loggedRecords = loggedRecordsMethod();
     const parsed = JSON.parse(loggedRecords[0]);
-    // biome-ignore lint/performance/noDelete: Would change behaviour of the test
+
     delete parsed.hostname;
-    // biome-ignore lint/performance/noDelete: Would change behaviour of the test
     delete parsed.level;
-    // biome-ignore lint/performance/noDelete: Would change behaviour of the test
     delete parsed.level_name;
-    // biome-ignore lint/performance/noDelete: Would change behaviour of the test
     delete parsed.timestamp;
 
     assert.deepStrictEqual(parsed, toRedactFields.expected_output);