@ogcio/o11y-sdk-node 0.3.1 → 0.4.1

package/lib/internals/redaction/pii-detection.ts

@@ -0,0 +1,113 @@
+import type { AnyValue, AnyValueMap } from "@opentelemetry/api-logs";
+import { Redactor } from "./redactors/index.js";
+
+const decoder = new TextDecoder();
+const encoder = new TextEncoder();
+
+export type PIISource = "trace" | "log" | "metric";
+
+/**
+ * Checks whether a string contains URI-encoded components.
+ *
+ * @param {string} value - The string to inspect.
+ * @returns {boolean} `true` if the string is encoded, `false` otherwise.
+ */
+export function _containsEncodedComponents(value: string): boolean {
+  try {
+    const decodedURIComponent = decodeURIComponent(value);
+    if (decodeURI(value) !== decodedURIComponent) {
+      return true;
+    }
+
+    if (value !== decodedURIComponent) {
+      return (
+        encodeURIComponent(decodedURIComponent) === value ||
+        encodeURI(decodedURIComponent) === value
+      );
+    }
+  } catch {
+    return false;
+  }
+
+  return false;
+}
+
+/**
+ * Cleans a string by redacting configured PIIs and emitting metrics for redacted values.
+ *
+ * If the string is URL-encoded, it will be decoded before redaction.
+ *
+ * @template T
+ *
+ * @param {string} value - The input value to sanitize.
+ * @param {"trace" | "log"} source - The source context of the input, used in metrics.
+ * @param {Redactor[]} redactors - The string processors containing the redaction logic.
+ *
+ * @returns {string} The cleaned string with any configured PII replaced by `[REDACTED PII_TYPE]`.
+ */
+export function _cleanStringPII(
+  value: string,
+  source: PIISource,
+  redactors: Redactor[],
+): string {
+  if (typeof value !== "string") {
+    return value;
+  }
+
+  let kind: "string" | "url" = "string";
+  let decodedValue: string = value;
+
+  if (_containsEncodedComponents(value)) {
+    decodedValue = decodeURIComponent(value);
+    kind = "url";
+  }
+  return redactors.reduce(
+    (redactedValue: string, currentRedactor): string =>
+      currentRedactor(redactedValue, source, kind),
+    decodedValue,
+  );
+}
+
+export function _recursiveObjectClean<T extends AnyValue>(
+  value: T,
+  source: PIISource,
+  redactors: Redactor[],
+): T {
+  if (typeof value === "string") {
+    return _cleanStringPII(value, source, redactors) as T;
+  }
+
+  if (
+    typeof value === "number" ||
+    typeof value === "boolean" ||
+    value == null
+  ) {
+    return value;
+  }
+
+  if (value instanceof Uint8Array) {
+    try {
+      const decoded = decoder.decode(value);
+      const sanitized = _cleanStringPII(decoded, source, redactors);
+      return encoder.encode(sanitized) as T;
+    } catch {
+      return value;
+    }
+  }
+
+  if (Array.isArray(value)) {
+    return value.map((value) =>
+      _recursiveObjectClean(value, source, redactors),
+    ) as T;
+  }
+
+  if (typeof value === "object") {
+    const sanitized: AnyValueMap = {};
+    for (const [key, val] of Object.entries(value)) {
+      sanitized[key] = _recursiveObjectClean(val, source, redactors);
+    }
+    return sanitized as T;
+  }
+
+  return value;
+}

package/lib/internals/redaction/redactors/email.ts

@@ -0,0 +1,58 @@
+import { _getPIICounterRedactionMetric } from "../../shared-metrics.js";
+
+const EMAIL_REGEX = /[\p{L}\p{N}._%+-]+@((?:[\p{L}\p{N}-]+\.)+[\p{L}]{2,})/giu;
+
+/**
+ * Redacts all email addresses in the input string and collects metadata.
+ *
+ * @param {string} value The input string potentially containing email addresses.
+ * @returns {{
+ *   redacted: string,
+ *   count: number,
+ *   domains: Record<string, number>
+ * }}
+ *
+ * An object containing:
+ *   - `redacted`: the string with email addresses replaced by `[REDACTED EMAIL]`
+ *   - `count`: total number of email addresses redacted
+ *   - `domains`: a map of domain names to the number of times they were redacted
+ */
+function _redactEmails(value: string): {
+  redacted: string;
+  count: number;
+  domains: Record<string, number>;
+} {
+  let count = 0;
+  const domains: Record<string, number> = {};
+
+  const redacted = value.replace(EMAIL_REGEX, (_, domain) => {
+    count++;
+    domains[domain] = (domains[domain] || 0) + 1;
+    return "[REDACTED EMAIL]";
+  });
+
+  return { redacted, count, domains };
+}
+
+/**
+ * Redacts provided input and collects metadata metrics about redacted email domains,
+ * data source and kind.
+ *
+ * @param {string} value The input string potentially containing email addresses.
+ * @returns {string} the redacted value
+ */
+export const emailRedactor = (value: string, source: string, kind: string) => {
+  const { redacted, count, domains } = _redactEmails(value);
+
+  if (count > 0) {
+    for (const [domain, domainCount] of Object.entries(domains)) {
+      _getPIICounterRedactionMetric().add(domainCount, {
+        pii_type: "email",
+        redaction_source: source,
+        pii_email_domain: domain,
+        pii_format: kind,
+      });
+    }
+  }
+  return redacted;
+};

package/lib/internals/redaction/redactors/index.ts

@@ -0,0 +1,12 @@
+import { NodeSDKConfig } from "../../../index.js";
+import { emailRedactor } from "./email.js";
+import { ipRedactor } from "./ip.js";
+
+export type Redactor = (value: string, source: string, kind: string) => string;
+
+export type RedactorKeys = keyof NonNullable<NodeSDKConfig["detection"]>;
+
+export const redactors: Record<RedactorKeys, Redactor> = {
+  email: emailRedactor,
+  ip: ipRedactor,
+};

package/lib/internals/redaction/redactors/ip.ts

@@ -0,0 +1,68 @@
+import { _getPIICounterRedactionMetric } from "../../shared-metrics.js";
+
+// Generous IP address matchers (might match some invalid addresses like 192.168.01.1)
+const IPV4_REGEX =
+  /(?<!\d)(?:%[0-9A-Fa-f]{2})?(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)(\.(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)){3}(?:%[0-9A-Fa-f]{2})?(?!\d)/gi;
+const IPV6_REGEX =
+  /(?<![0-9a-f:])(?:%[0-9A-Fa-f]{2})?((?:[0-9A-Fa-f]{1,4}:){7}[0-9A-Fa-f]{1,4}|(?:[0-9A-Fa-f]{1,4}:){1,7}:|:(?::[0-9A-Fa-f]{1,4}){1,7}|(?:[0-9A-Fa-f]{1,4}:){1,6}:[0-9A-Fa-f]{1,4}|(?:[0-9A-Fa-f]{1,4}:){1,5}(?::[0-9A-Fa-f]{1,4}){1,2}|(?:[0-9A-Fa-f]{1,4}:){1,4}(?::[0-9A-Fa-f]{1,4}){1,3}|(?:[0-9A-Fa-f]{1,4}:){1,3}(?::[0-9A-Fa-f]{1,4}){1,4}|(?:[0-9A-Fa-f]{1,4}:){1,2}(?::[0-9A-Fa-f]{1,4}){1,5}|[0-9A-Fa-f]{1,4}:(?::[0-9A-Fa-f]{1,4}){1,6}|:(?::[0-9A-Fa-f]{1,4}){1,7}:?|(?:[0-9A-Fa-f]{1,4}:){1,4}:(?:25[0-5]|2[0-4]\d|1\d\d|\d{1,2})(?:\.(?:25[0-5]|2[0-4]\d|1\d\d|\d{1,2})){3})(?:%[0-9A-Fa-f]{2})?(?![0-9a-f:])/gi;
+
+/**
+ * Redacts all ip addresses in the input string and collects metadata.
+ *
+ * @param {string} value The input string potentially containing ip addresses.
+ * @returns {{
+ *   redacted: string,
+ *   count: number,
+ *   domains: Record<string, number>
+ * }}
+ *
+ * An object containing:
+ *   - `redacted`: the string with IP addresses replaced by `[REDACTED IPV*]`
+ *   - `counters`: total number of addresses redacted by IPv* type
+ *   - `domains`: a map of domain names to the number of times they were redacted
+ */
+function _redactIps(value: string): {
+  redacted: string;
+  counters: Record<string, number>;
+} {
+  const counters: Record<string, number> = {};
+  const redacted = value
+    .replace(IPV4_REGEX, () => {
+      counters["IPv4"] = (counters["IPv4"] || 0) + 1;
+      return "[REDACTED IPV4]";
+    })
+    .replace(IPV6_REGEX, () => {
+      counters["IPv4"] = (counters["IPv4"] || 0) + 1;
+      return "[REDACTED IPV6]";
+    });
+  return { redacted, counters };
+}
+
+/**
+ * Redacts provided input and collects metadata metrics about redacted IPs,
+ * data source and kind.
+ *
+ * @param {string} value The input string potentially containing IP addresses.
+ * @param {string} source The source of the attribute being redacted (log, span, metric).
+ * @param {string} kind The type of the data structure containing the PII
+ * @returns {string} the redacted value
+ */
+export const ipRedactor = (
+  value: string,
+  source: string,
+  kind: string,
+): string => {
+  const { redacted, counters } = _redactIps(value);
+
+  Object.entries(counters).forEach(([type, counter]) => {
+    if (counter > 0) {
+      _getPIICounterRedactionMetric().add(counter, {
+        pii_type: type,
+        redaction_source: source,
+        pii_format: kind,
+      });
+    }
+  });
+
+  return redacted;
+};

package/lib/internals/shared-metrics.ts

@@ -1,6 +1,6 @@
 import { Attributes, Counter } from "@opentelemetry/api";
 import { getMetric } from "../metrics.js";
-import { PIISource } from "./pii-detection.js";
+import { PIISource } from "./redaction/pii-detection.js";
 
 interface RedactionMetric extends Attributes {
   /** Type of PII redacted (e.g., "email", "phone"). */

package/lib/processor/enrich-logger-processor.ts

@@ -1,4 +1,4 @@
-import { LogRecord, LogRecordProcessor } from "@opentelemetry/sdk-logs";
+import { SdkLogRecord, LogRecordProcessor } from "@opentelemetry/sdk-logs";
 import { Context } from "@opentelemetry/api";
 import { SignalAttributeValue } from "../index.js";
 
@@ -18,7 +18,7 @@ export class EnrichLogProcessor implements LogRecordProcessor {
   forceFlush(): Promise<void> {
     return Promise.resolve();
   }
-  onEmit(logRecord: LogRecord, _context?: Context): void {
+  onEmit(logRecord: SdkLogRecord, _context?: Context): void {
     if (this._spanAttributes) {
       for (const [key, value] of Object.entries(this._spanAttributes)) {
         logRecord.setAttribute(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ogcio/o11y-sdk-node",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "description": "Opentelemetry standard instrumentation SDK for NodeJS based project",
   "main": "dist/index.js",
   "type": "module",
@@ -22,26 +22,26 @@
     "@grpc/grpc-js": "^1.13.4",
     "@opentelemetry/api": "^1.9.0",
     "@opentelemetry/api-logs": "^0.203.0",
-    "@opentelemetry/auto-instrumentations-node": "^0.60.1",
+    "@opentelemetry/auto-instrumentations-node": "^0.62.1",
     "@opentelemetry/core": "^2.0.1",
-    "@opentelemetry/exporter-logs-otlp-grpc": "^0.202.0",
-    "@opentelemetry/exporter-logs-otlp-http": "^0.202.0",
-    "@opentelemetry/exporter-metrics-otlp-grpc": "^0.202.0",
-    "@opentelemetry/exporter-metrics-otlp-http": "^0.202.0",
-    "@opentelemetry/exporter-trace-otlp-grpc": "^0.202.0",
-    "@opentelemetry/exporter-trace-otlp-http": "^0.202.0",
-    "@opentelemetry/instrumentation": "^0.202.0",
-    "@opentelemetry/otlp-exporter-base": "^0.202.0",
+    "@opentelemetry/exporter-logs-otlp-grpc": "^0.203.0",
+    "@opentelemetry/exporter-logs-otlp-http": "^0.203.0",
+    "@opentelemetry/exporter-metrics-otlp-grpc": "^0.203.0",
+    "@opentelemetry/exporter-metrics-otlp-http": "^0.203.0",
+    "@opentelemetry/exporter-trace-otlp-grpc": "^0.203.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.203.0",
+    "@opentelemetry/instrumentation": "^0.203.0",
+    "@opentelemetry/otlp-exporter-base": "^0.203.0",
     "@opentelemetry/resources": "^2.0.1",
-    "@opentelemetry/sdk-logs": "^0.202.0",
+    "@opentelemetry/sdk-logs": "^0.203.0",
     "@opentelemetry/sdk-metrics": "^2.0.1",
-    "@opentelemetry/sdk-node": "^0.202.0",
+    "@opentelemetry/sdk-node": "^0.203.0",
     "@opentelemetry/sdk-trace-base": "^2.0.1"
   },
   "devDependencies": {
-    "@types/node": "^24.0.10",
+    "@types/node": "^24.3.0",
     "@vitest/coverage-v8": "^3.2.4",
-    "tsx": "^4.20.3",
+    "tsx": "^4.20.5",
     "typescript": "^5.8.3",
     "vitest": "^3.2.4"
   },

package/test/internals/pii-detection.test.ts

@@ -1,9 +1,12 @@
 import { describe, expect, it, vi, beforeEach } from "vitest";
 import {
   _cleanStringPII,
-  _cleanLogBodyPII,
-} from "../../lib/internals/pii-detection.js";
+  _containsEncodedComponents,
+  _recursiveObjectClean,
+} from "../../lib/internals/redaction/pii-detection.js";
 import * as sharedMetrics from "../../lib/internals/shared-metrics.js";
+import { emailRedactor } from "../../lib/internals/redaction/redactors/email";
+import { ipRedactor } from "../../lib/internals/redaction/redactors/ip";
 
 describe("PII Detection Utils", () => {
   const mockMetricAdd = vi.fn();
@@ -16,9 +19,9 @@ describe("PII Detection Utils", () => {
   });
 
   describe("_cleanStringPII", () => {
-    it("redacts plain email", () => {
+    it("redacts plain PII", () => {
       const input = "admin@example.com";
-      const output = _cleanStringPII(input, "log");
+      const output = _cleanStringPII(input, "log", [emailRedactor]);
 
       expect(output).toBe("[REDACTED EMAIL]");
       expect(mockMetricAdd).toHaveBeenCalledWith(
@@ -33,7 +36,7 @@ describe("PII Detection Utils", () => {
 
     it("redacts email in URL-encoded string", () => {
       const input = "user%40gmail.com";
-      const output = _cleanStringPII(input, "log");
+      const output = _cleanStringPII(input, "log", [emailRedactor]);
 
       expect(output).toBe("[REDACTED EMAIL]");
       expect(mockMetricAdd).toHaveBeenCalledWith(
@@ -45,36 +48,57 @@ describe("PII Detection Utils", () => {
       );
     });
 
-    it("handles strings without email unchanged", () => {
-      const input = "hello world";
-      const output = _cleanStringPII(input, "log");
+    it("redacts ip in URL-encoded string", () => {
+      const input = "%20127.0.0.1";
+      const output = _cleanStringPII(input, "log", [ipRedactor]);
 
-      expect(output).toBe("hello world");
-      expect(mockMetricAdd).not.toHaveBeenCalled();
+      expect(output).toBe(" [REDACTED IPV4]");
+      expect(mockMetricAdd).toHaveBeenCalledWith(
+        1,
+        expect.objectContaining({
+          pii_format: "url",
+          pii_type: "IPv4",
+          redaction_source: "log",
+        }),
+      );
     });
 
-    it("handles array of strings", () => {
-      const input = ["one@gmail.com", "two@example.com"];
-      const output = _cleanStringPII(input, "log");
+    it("handles strings without PII unchanged", () => {
+      const input = "hello world";
+      const output = _cleanStringPII(input, "log", [emailRedactor]);
 
-      expect(output).toEqual(["[REDACTED EMAIL]", "[REDACTED EMAIL]"]);
-      expect(mockMetricAdd).toHaveBeenCalledTimes(2);
+      expect(output).toBe("hello world");
+      expect(mockMetricAdd).not.toHaveBeenCalled();
     });
 
     it("ignores non-string input", () => {
-      expect(_cleanStringPII(1234, "trace")).toBe(1234);
-      expect(_cleanStringPII(true, "trace")).toBe(true);
-      expect(_cleanStringPII(undefined, "trace")).toBeUndefined();
+      // @ts-expect-error
+      expect(_cleanStringPII(1234, "trace", [emailRedactor])).toBe(1234);
+      // @ts-expect-error
+      expect(_cleanStringPII(true, "trace", [emailRedactor])).toBe(true);
+      expect(
+        _cleanStringPII(undefined, "trace", [emailRedactor]),
+      ).toBeUndefined();
       expect(mockMetricAdd).not.toHaveBeenCalled();
     });
   });
 
-  describe("_cleanLogBodyPII", () => {
-    it("cleans string email", () => {
-      const result = _cleanLogBodyPII("demo@abc.com");
+  describe("_recursiveObjectClean", () => {
+    it("cleans string PII", () => {
+      const result = _recursiveObjectClean("demo@abc.com", "log", [
+        emailRedactor,
+      ]);
       expect(result).toBe("[REDACTED EMAIL]");
     });
 
+    it("cleans array of strings", () => {
+      const input = ["one@gmail.com", "two@example.com"];
+      const output = _recursiveObjectClean(input, "log", [emailRedactor]);
+
+      expect(output).toEqual(["[REDACTED EMAIL]", "[REDACTED EMAIL]"]);
+      expect(mockMetricAdd).toHaveBeenCalledTimes(2);
+    });
+
     it("cleans deeply nested object", () => {
       const input = {
         user: {
@@ -86,7 +110,7 @@ describe("PII Detection Utils", () => {
         status: "active",
       };
 
-      const result = _cleanLogBodyPII(input);
+      const result = _recursiveObjectClean(input, "log", [emailRedactor]);
 
       expect(result).toEqual({
         user: {
@@ -102,7 +126,7 @@ describe("PII Detection Utils", () => {
     it("cleans Uint8Array input", () => {
       const str = "admin@gmail.com";
       const buffer = new TextEncoder().encode(str);
-      const result = _cleanLogBodyPII(buffer);
+      const result = _recursiveObjectClean(buffer, "log", [emailRedactor]);
       const decoded = new TextDecoder().decode(result as Uint8Array);
 
       expect(decoded).toBe("[REDACTED EMAIL]");
@@ -110,7 +134,7 @@ describe("PII Detection Utils", () => {
 
     it("skips malformed Uint8Array decode", () => {
       const corrupted = new Uint8Array([0xff, 0xfe, 0xfd]);
-      const result = _cleanLogBodyPII(corrupted);
+      const result = _recursiveObjectClean(corrupted, "log", [emailRedactor]);
 
       // Should return a Uint8Array, but unmodified/redaction should not happen
       expect(result).toBeInstanceOf(Uint8Array);
@@ -118,11 +142,11 @@ describe("PII Detection Utils", () => {
     });
 
     it("cleans arrays of values", () => {
-      const result = _cleanLogBodyPII([
-        "bob@abc.com",
-        123,
-        { nested: "jane@example.com" },
-      ]);
+      const result = _recursiveObjectClean(
+        ["bob@abc.com", 123, { nested: "jane@example.com" }],
+        "log",
+        [emailRedactor],
+      );
 
       expect(result).toEqual([
         "[REDACTED EMAIL]",
@@ -132,10 +156,110 @@ describe("PII Detection Utils", () => {
     });
 
     it("passes null and boolean through", () => {
-      expect(_cleanLogBodyPII(null)).toBeNull();
-      expect(_cleanLogBodyPII(undefined)).toBeUndefined();
-      expect(_cleanLogBodyPII(true)).toBe(true);
-      expect(_cleanLogBodyPII(false)).toBe(false);
+      expect(_recursiveObjectClean(null, "log", [emailRedactor])).toBeNull();
+      expect(
+        _recursiveObjectClean(undefined, "log", [emailRedactor]),
+      ).toBeUndefined();
+      expect(_recursiveObjectClean(true, "log", [emailRedactor])).toBe(true);
+      expect(_recursiveObjectClean(false, "log", [emailRedactor])).toBe(false);
+    });
+  });
+
+  describe("_containsEncodedComponents", () => {
+    describe("should return true for properly URL encoded strings", () => {
+      it.each([
+        ["hello%20world", "Space encoded as %20"],
+        ["test%2Bvalue", "Plus sign encoded as %2B"],
+        ["path%2Fto%2Ffile", "Forward slashes encoded"],
+        ["user%40domain.com", "@ symbol encoded"],
+        ["100%25%20off", "Percent and space encoded"],
+        ["a%3Db%26c%3Dd", "Query parameters (a=b&c=d)"],
+        ["caf%C3%A9", "UTF-8 encoded (café)"],
+        ["price%3A%20%2410", "Colon, space, dollar ($10)"],
+        ["%22quoted%22", "Double quotes encoded"],
+        ["https%3A%2F%2Fexample.com", "Full URL encoded"],
+        ["file%20name.txt", "filename encoded"],
+        ["search%3Fq%3Dhello%20world", "Query string encoded"],
+        ["%3C%3E%26%22%27", "HTML special chars encoded (<>&\"')"],
+        ["%E2%9C%93", "UTF-8 checkmark (✓) encoded"],
+        ["test%2b", "Lowercase hex"],
+        ["%E4%B8%AD%E6%96%87", "Chinese characters encoded"],
+      ])('should detect "%s" as URL encoded (%s)', (input, description) => {
+        expect(_containsEncodedComponents(input)).toBe(true);
+      });
+    });
+
+    describe("should return false for non-URL encoded strings", () => {
+      it.each([
+        ["test", "Simple ASCII string"],
+        ["hello world", "Unencoded space"],
+        ["user@domain.com", "Unencoded email"],
+        ["simple123", "Alphanumeric only"],
+        ["", "Empty string"],
+        ["25%%", "Literal percent signs"],
+        ["100% off", "Percent without hex digits"],
+        ["test%2", "Incomplete percent encoding"],
+        ["hello%ZZ", "Invalid hex digits"],
+        ["test%2G", "Invalid hex digit G"],
+        ["bad%encoding%here", "Percent without hex pairs"],
+        ["hello%20world and more", "Partially encoded string"],
+        ["hello%20world%21%20how%20are%20you", "Overly encoded string"],
+        ["café", "Unicode characters (unencoded)"],
+        ["hello+world", "Plus sign (form encoding style)"],
+        ["test%", "Trailing percent"],
+        ["hello%20world%", "Encoded content with trailing percent"],
+        ["%", "Single percent"],
+        ["%%", "Double percent"],
+        ["normal text with % symbols", "Text with percent but no encoding"],
+        ["price: $100%", "Currency with percent"],
+        ["file.txt", "Simple filename"],
+        ["path/to/file", "Unencoded path"],
+        ["query?param=value", "Unencoded query string"],
+        ["hello%world", "Percent without following hex"],
+        ["test%1", "Single hex digit after percent"],
+        ["hello%zz", "Non-hex characters after percent"],
+      ])('should not detect "%s" as URL encoded (%s)', (input, description) => {
+        expect(_containsEncodedComponents(input)).toBe(false);
+      });
+    });
+
+    describe("Error handling", () => {
+      it.each([
+        ["%C0%80", "Overlong UTF-8 encoding (security concern)"],
+        ["%ED%A0%80", "UTF-8 surrogate (invalid)"],
+        ["%FF%FE", "Invalid UTF-8 sequence"],
+        ["test%20%ZZ", "Mix of valid and invalid encoding"],
+      ])('should handle "%s" (%s)', (input, description) => {
+        // These should not throw errors
+        expect(() => _containsEncodedComponents(input)).not.toThrow();
+
+        // Most of these should return false due to invalid sequences
+        // or security-related encoding issues
+        const result = _containsEncodedComponents(input);
+        expect(typeof result).toBe("boolean");
+      });
+    });
+
+    describe("real-world url examples", () => {
+      it.each([
+        [
+          "https%3A%2F%2Fgoogle.com%2Fsearch%3Fq%3Djavascript",
+          "Encoded Google search URL",
+        ],
+        ["The%20quick%20brown%20fox", "Sentence with spaces encoded"],
+        [
+          "/api/user?body=here%20are%20all%20my%20secrets",
+          "contextually encoded API path",
+        ],
+        ["redirect_uri=https%3A%2F%2Fapp.com%2Fcallback", "OAuth redirect URI"],
+        ["data%3Atext%2Fplain%3Bbase64%2CSGVsbG8%3D", "Data URL encoded"],
+      ])('real-world case: "%s" (%s)', (input, description) => {
+        const result = _containsEncodedComponents(input);
+
+        // Verify the function doesn't crash
+        expect(typeof result).toBe("boolean");
+        expect(result).toBe(true);
+      });
     });
   });
 });

package/test/internals/redactors/email.test.ts

@@ -0,0 +1,81 @@
+import {
+  describe,
+  expect,
+  it,
+  vi,
+  beforeEach,
+  beforeAll,
+  afterAll,
+} from "vitest";
+
+import * as sharedMetrics from "../../../lib/internals/shared-metrics.js";
+import { ipRedactor } from "../../../lib/internals/redaction/redactors/ip";
+import { emailRedactor } from "../../../lib/internals/redaction/redactors/email";
+
+describe("Email Redaction utils", () => {
+  describe("tracks metrics", () => {
+    const mockMetricAdd = vi.fn();
+
+    beforeEach(() => {
+      vi.restoreAllMocks();
+      vi.spyOn(sharedMetrics, "_getPIICounterRedactionMetric").mockReturnValue({
+        add: mockMetricAdd,
+      });
+    });
+
+    it("redacts plain PII and tracks redaction with metric", () => {
+      const input = "admin@example.com";
+      const output = emailRedactor(input, "log", "string");
+
+      expect(output).toBe("[REDACTED EMAIL]");
+      expect(mockMetricAdd).toHaveBeenCalledWith(
+        1,
+        expect.objectContaining({
+          pii_email_domain: "example.com",
+          pii_type: "email",
+          redaction_source: "log",
+        }),
+      );
+    });
+
+    it("handles strings without PII unchanged", () => {
+      const input = "hello world";
+      const output = ipRedactor(input, "log", "string");
+
+      expect(output).toBe("hello world");
+      expect(mockMetricAdd).not.toHaveBeenCalled();
+    });
+  });
+
+  describe("Redacts email addresses", () => {
+    beforeAll(() => {
+      vi.spyOn(sharedMetrics, "_getPIICounterRedactionMetric").mockReturnValue({
+        add: vi.fn(),
+      });
+    });
+
+    afterAll(() => {
+      vi.restoreAllMocks();
+    });
+
+    it.each`
+      value                                  | expectedRedactedValue
+      ${"user+tag@example.com"}              | ${"[REDACTED EMAIL]"}
+      ${"user.name+tag+sorting@example.com"} | ${"[REDACTED EMAIL]"}
+      ${"x@example.museum"}                  | ${"[REDACTED EMAIL]"}
+      ${"a.b-c_d@example.co.uk"}             | ${"[REDACTED EMAIL]"}
+      ${"üser@example.de"}                   | ${"[REDACTED EMAIL]"}
+      ${"john.doe@xn--exmple-cua.com"}       | ${"[REDACTED EMAIL]"}
+      ${"üser@example.de"}                   | ${"[REDACTED EMAIL]"}
+      ${"plainaddress"}                      | ${"plainaddress"}
+      ${"@missinglocal.org"}                 | ${"@missinglocal.org"}
+      ${"user@invalid_domain.com"}           | ${"user@invalid_domain.com"}
+    `(
+      "returns $expectedRedactedValue for value '$value'",
+      async ({ value, expectedRedactedValue }: Record<string, string>) => {
+        const result = emailRedactor(value, "log", "string");
+        expect(result).toBe(expectedRedactedValue);
+      },
+    );
+  });
+});