@logtape/redaction 0.11.0 → 0.12.0-dev.181

package/pattern.test.ts

@@ -0,0 +1,351 @@
+import { suite } from "@hongminhee/suite";
+import type {
+  ConsoleFormatter,
+  LogRecord,
+  TextFormatter,
+} from "@logtape/logtape";
+import { assert } from "@std/assert/assert";
+import { assertEquals } from "@std/assert/equals";
+import { assertMatch } from "@std/assert/match";
+import { assertThrows } from "@std/assert/throws";
+import {
+  CREDIT_CARD_NUMBER_PATTERN,
+  EMAIL_ADDRESS_PATTERN,
+  JWT_PATTERN,
+  KR_RRN_PATTERN,
+  redactByPattern,
+  type RedactionPattern,
+  US_SSN_PATTERN,
+} from "./pattern.ts";
+
+const test = suite(import.meta);
+
+test("EMAIL_ADDRESS_PATTERN", () => {
+  const { pattern, replacement } = EMAIL_ADDRESS_PATTERN;
+
+  // Test valid email addresses
+  const validEmails = [
+    "user@example.com",
+    "first.last@example.co.uk",
+    "user+tag@example.org",
+    "user123@sub.domain.com",
+    "user-name@example.com",
+    "user_name@example.com",
+    "user.name@example-domain.co",
+    // Ensure international domains work:
+    // cSpell: disable
+    "用户@例子.世界",
+    "пользователь@пример.рф",
+    // cSpell: enable
+  ];
+
+  for (const email of validEmails) {
+    assertMatch(email, pattern);
+    pattern.lastIndex = 0;
+  }
+
+  // Test replacements
+  assertEquals(
+    "Contact at user@example.com for more info.".replaceAll(
+      pattern,
+      replacement as string,
+    ),
+    "Contact at REDACTED@EMAIL.ADDRESS for more info.",
+  );
+  assertEquals(
+    "My email is user@example.com".replaceAll(pattern, replacement as string),
+    "My email is REDACTED@EMAIL.ADDRESS",
+  );
+  assertEquals(
+    "Emails: user1@example.com and user2@example.org".replaceAll(
+      pattern,
+      replacement as string,
+    ),
+    "Emails: REDACTED@EMAIL.ADDRESS and REDACTED@EMAIL.ADDRESS",
+  );
+
+  // Ensure the global flag is set
+  assert(
+    pattern.global,
+    "EMAIL_ADDRESS_PATTERN should have the global flag set",
+  );
+});
+
+test("CREDIT_CARD_NUMBER_PATTERN", () => {
+  const { pattern, replacement } = CREDIT_CARD_NUMBER_PATTERN;
+
+  // Test valid credit card numbers with dashes
+  assertMatch("1234-5678-9012-3456", pattern); // Regular 16-digit card
+  pattern.lastIndex = 0;
+  assertMatch("1234-5678-901234", pattern); // American Express format
+  pattern.lastIndex = 0;
+
+  // Test replacements
+  assertEquals(
+    "Card: 1234-5678-9012-3456".replaceAll(pattern, replacement as string),
+    "Card: XXXX-XXXX-XXXX-XXXX",
+  );
+  assertEquals(
+    "AmEx: 1234-5678-901234".replaceAll(pattern, replacement as string),
+    "AmEx: XXXX-XXXX-XXXX-XXXX",
+  );
+  assertEquals(
+    "Cards: 1234-5678-9012-3456 and 1234-5678-901234".replaceAll(
+      pattern,
+      replacement as string,
+    ),
+    "Cards: XXXX-XXXX-XXXX-XXXX and XXXX-XXXX-XXXX-XXXX",
+  );
+});
+
+test("US_SSN_PATTERN", () => {
+  const { pattern, replacement } = US_SSN_PATTERN;
+
+  // Test valid US Social Security numbers
+  assertMatch("123-45-6789", pattern);
+  pattern.lastIndex = 0;
+
+  // Test replacements
+  assertEquals(
+    "SSN: 123-45-6789".replaceAll(pattern, replacement as string),
+    "SSN: XXX-XX-XXXX",
+  );
+  assertEquals(
+    "SSNs: 123-45-6789 and 987-65-4321".replaceAll(
+      pattern,
+      replacement as string,
+    ),
+    "SSNs: XXX-XX-XXXX and XXX-XX-XXXX",
+  );
+});
+
+test("KR_RRN_PATTERN", () => {
+  const { pattern, replacement } = KR_RRN_PATTERN;
+
+  // Test valid South Korean resident registration numbers
+  assertMatch("123456-7890123", pattern);
+  pattern.lastIndex = 0;
+
+  // Test replacements
+  assertEquals(
+    "RRN: 123456-7890123".replaceAll(pattern, replacement as string),
+    "RRN: XXXXXX-XXXXXXX",
+  );
+  assertEquals(
+    "RRNs: 123456-7890123 and 654321-0987654".replaceAll(
+      pattern,
+      replacement as string,
+    ),
+    "RRNs: XXXXXX-XXXXXXX and XXXXXX-XXXXXXX",
+  );
+});
+
+test("JWT_PATTERN", () => {
+  const { pattern, replacement } = JWT_PATTERN;
+
+  // Test valid JWT tokens
+  const sampleJwt =
+    "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c";
+  assertMatch(sampleJwt, pattern);
+  pattern.lastIndex = 0;
+
+  // Test replacements
+  assertEquals(
+    `Token: ${sampleJwt}`.replaceAll(pattern, replacement as string),
+    "Token: [JWT REDACTED]",
+  );
+  assertEquals(
+    `First: ${sampleJwt}, Second: ${sampleJwt}`.replaceAll(
+      pattern,
+      replacement as string,
+    ),
+    "First: [JWT REDACTED], Second: [JWT REDACTED]",
+  );
+});
+
+test("redactByPattern(TextFormatter)", () => {
+  { // redacts sensitive information in text output
+    // Create a simple TextFormatter that returns a string
+    const formatter: TextFormatter = (record: LogRecord) => {
+      return `[${record.level.toUpperCase()}] ${record.message.join(" ")}`;
+    };
+
+    // Test data with multiple patterns to redact
+    const record: LogRecord = {
+      level: "info",
+      category: ["test"],
+      message: [
+        "Sensitive info: email = user@example.com, cc = 1234-5678-9012-3456, ssn = 123-45-6789",
+      ],
+      rawMessage:
+        "Sensitive info: email = user@example.com, cc = 1234-5678-9012-3456, ssn = 123-45-6789",
+      timestamp: Date.now(),
+      properties: {},
+    };
+
+    // Apply redaction with multiple patterns
+    const redactedFormatter = redactByPattern(formatter, [
+      EMAIL_ADDRESS_PATTERN,
+      CREDIT_CARD_NUMBER_PATTERN,
+      US_SSN_PATTERN,
+    ]);
+
+    const output = redactedFormatter(record);
+
+    // Verify all sensitive data was redacted
+    assertEquals(
+      output,
+      "[INFO] Sensitive info: email = REDACTED@EMAIL.ADDRESS, cc = XXXX-XXXX-XXXX-XXXX, ssn = XXX-XX-XXXX",
+    );
+  }
+
+  { // handles function-based replacements
+    const formatter: TextFormatter = (record: LogRecord) => {
+      return record.message.join(" ");
+    };
+
+    // Custom pattern with function replacement
+    const customPattern: RedactionPattern = {
+      pattern: /\b(password|pw)=([^\s,]+)/g,
+      replacement: (_match, key) => `${key}=[HIDDEN]`,
+    };
+
+    const record: LogRecord = {
+      level: "info",
+      category: ["test"],
+      message: ["Credentials: password=secret123, pw=another-secret"],
+      rawMessage: "Credentials: password=secret123, pw=another-secret",
+      timestamp: Date.now(),
+      properties: {},
+    };
+
+    const redactedFormatter = redactByPattern(formatter, [customPattern]);
+    const output = redactedFormatter(record);
+
+    assertEquals(
+      output,
+      "Credentials: password=[HIDDEN], pw=[HIDDEN]",
+    );
+  }
+
+  { // throws error if global flag is not set
+    const formatter: TextFormatter = (record: LogRecord) =>
+      record.message.join(" ");
+
+    const invalidPattern: RedactionPattern = {
+      pattern: /password/, // Missing global flag
+      replacement: "****",
+    };
+
+    assertThrows(
+      () => redactByPattern(formatter, [invalidPattern]),
+      TypeError,
+      "does not have the global flag set",
+    );
+  }
+});
+
+test("redactByPattern(ConsoleFormatter)", () => {
+  { // redacts sensitive information in console formatter arrays
+    // Create a simple ConsoleFormatter that returns an array of values
+    const formatter: ConsoleFormatter = (record: LogRecord) => {
+      return [
+        `[${record.level.toUpperCase()}]`,
+        ...record.message,
+      ];
+    };
+
+    // Create test record with sensitive data
+    const record: LogRecord = {
+      level: "info",
+      category: ["test"],
+      message: [
+        "User data:",
+        {
+          name: "John Doe",
+          email: "john@example.com",
+          creditCard: "1234-5678-9012-3456",
+        },
+      ],
+      rawMessage: "User data: [object Object]",
+      timestamp: Date.now(),
+      properties: {},
+    };
+
+    // Apply redaction
+    const redactedFormatter = redactByPattern(formatter, [
+      EMAIL_ADDRESS_PATTERN,
+      CREDIT_CARD_NUMBER_PATTERN,
+    ]);
+
+    const output = redactedFormatter(record);
+
+    // Verify output structure is preserved and data is redacted
+    assertEquals(output[0], "[INFO]");
+    assertEquals(output[1], "User data:");
+    assertEquals(
+      (output[2] as { name: string; email: string; creditCard: string }).name,
+      "John Doe",
+    );
+    assertEquals(
+      (output[2] as { name: string; email: string; creditCard: string })
+        .email,
+      "REDACTED@EMAIL.ADDRESS",
+    );
+    assertEquals(
+      (output[2] as { name: string; email: string; creditCard: string })
+        .creditCard,
+      "XXXX-XXXX-XXXX-XXXX",
+    );
+  }
+
+  { // handles nested objects and arrays in console output
+    const formatter: ConsoleFormatter = (record: LogRecord) => {
+      return [record.level, record.message];
+    };
+
+    const nestedData = {
+      user: {
+        contact: {
+          email: "user@example.com",
+          phone: "123-456-7890",
+        },
+        payment: {
+          cards: [
+            "1234-5678-9012-3456",
+            "8765-4321-8765-4321",
+          ],
+        },
+        documents: {
+          ssn: "123-45-6789",
+        },
+      },
+    };
+
+    const record: LogRecord = {
+      level: "info",
+      category: ["test"],
+      message: ["Data:", nestedData],
+      rawMessage: "Data: [object Object]",
+      timestamp: Date.now(),
+      properties: {},
+    };
+
+    const redactedFormatter = redactByPattern(formatter, [
+      EMAIL_ADDRESS_PATTERN,
+      CREDIT_CARD_NUMBER_PATTERN,
+      US_SSN_PATTERN,
+    ]);
+
+    const output = redactedFormatter(record);
+
+    // Verify deep redaction in nested structures
+    const resultData =
+      (output[1] as unknown[])[1] as unknown as typeof nestedData;
+    assertEquals(resultData.user.contact.email, "REDACTED@EMAIL.ADDRESS");
+    assertEquals(resultData.user.contact.phone, "123-456-7890"); // Not redacted
+    assertEquals(resultData.user.payment.cards[0], "XXXX-XXXX-XXXX-XXXX");
+    assertEquals(resultData.user.payment.cards[1], "XXXX-XXXX-XXXX-XXXX");
+    assertEquals(resultData.user.documents.ssn, "XXX-XX-XXXX");
+  }
+});

package/pattern.ts

@@ -0,0 +1,209 @@
+import type {
+  ConsoleFormatter,
+  LogRecord,
+  TextFormatter,
+} from "@logtape/logtape";
+
+/**
+ * A redaction pattern, which is a pair of regular expression and replacement
+ * string or function.
+ * @since 0.10.0
+ */
+export interface RedactionPattern {
+  /**
+   * The regular expression to match against.  Note that it must have the
+   * `g` (global) flag set, otherwise it will throw a `TypeError`.
+   */
+  readonly pattern: RegExp;
+
+  /**
+   * The replacement string or function.  If the replacement is a function,
+   * it will be called with the matched string and any capture groups (the same
+   * signature as `String.prototype.replaceAll()`).
+   */
+  readonly replacement:
+    | string
+    // deno-lint-ignore no-explicit-any
+    | ((match: string, ...rest: readonly any[]) => string);
+}
+
+/**
+ * A redaction pattern for email addresses.
+ * @since 0.10.0
+ */
+export const EMAIL_ADDRESS_PATTERN: RedactionPattern = {
+  pattern:
+    /[\p{L}0-9.!#$%&'*+/=?^_`{|}~-]+@[\p{L}0-9](?:[\p{L}0-9-]{0,61}[\p{L}0-9])?(?:\.[\p{L}0-9](?:[\p{L}0-9-]{0,61}[\p{L}0-9])?)+/gu,
+  replacement: "REDACTED@EMAIL.ADDRESS",
+};
+
+/**
+ * A redaction pattern for credit card numbers (including American Express).
+ * @since 0.10.0
+ */
+export const CREDIT_CARD_NUMBER_PATTERN: RedactionPattern = {
+  pattern: /(?:\d{4}-){3}\d{4}|(?:\d{4}-){2}\d{6}/g,
+  replacement: "XXXX-XXXX-XXXX-XXXX",
+};
+
+/**
+ * A redaction pattern for U.S. Social Security numbers.
+ * @since 0.10.0
+ */
+export const US_SSN_PATTERN: RedactionPattern = {
+  pattern: /\d{3}-\d{2}-\d{4}/g,
+  replacement: "XXX-XX-XXXX",
+};
+
+/**
+ * A redaction pattern for South Korean resident registration numbers
+ * (住民登錄番號).
+ * @since 0.10.0
+ */
+export const KR_RRN_PATTERN: RedactionPattern = {
+  pattern: /\d{6}-\d{7}/g,
+  replacement: "XXXXXX-XXXXXXX",
+};
+
+/**
+ * A redaction pattern for JSON Web Tokens (JWT).
+ * @since 0.10.0
+ */
+export const JWT_PATTERN: RedactionPattern = {
+  pattern: /eyJ[a-zA-Z0-9_-]*\.[a-zA-Z0-9_-]*\.[a-zA-Z0-9_-]*/g,
+  replacement: "[JWT REDACTED]",
+};
+
+/**
+ * A list of {@link RedactionPattern}s.
+ * @since 0.10.0
+ */
+export type RedactionPatterns = readonly RedactionPattern[];
+
+/**
+ * Applies data redaction to a {@link TextFormatter}.
+ *
+ * Note that there are some built-in redaction patterns:
+ *
+ * - {@link CREDIT_CARD_NUMBER_PATTERN}
+ * - {@link EMAIL_ADDRESS_PATTERN}
+ * - {@link JWT_PATTERN}
+ * - {@link KR_RRN_PATTERN}
+ * - {@link US_SSN_PATTERN}
+ *
+ * @example
+ * ```ts
+ * import { getFileSink } from "@logtape/file";
+ * import { getAnsiColorFormatter } from "@logtape/logtape";
+ * import {
+ *   CREDIT_CARD_NUMBER_PATTERN,
+ *   EMAIL_ADDRESS_PATTERN,
+ *   JWT_PATTERN,
+ *   redactByPattern,
+ * } from "@logtape/redaction";
+ *
+ * const formatter = redactByPattern(getAnsiConsoleFormatter(), [
+ *   CREDIT_CARD_NUMBER_PATTERN,
+ *   EMAIL_ADDRESS_PATTERN,
+ *   JWT_PATTERN,
+ * ]);
+ * const sink = getFileSink("my-app.log", { formatter });
+ * ```
+ * @param formatter The text formatter to apply redaction to.
+ * @param patterns The redaction patterns to apply.
+ * @returns The redacted text formatter.
+ * @since 0.10.0
+ */
+export function redactByPattern(
+  formatter: TextFormatter,
+  patterns: RedactionPatterns,
+): TextFormatter;
+
+/**
+ * Applies data redaction to a {@link ConsoleFormatter}.
+ *
+ * Note that there are some built-in redaction patterns:
+ *
+ * - {@link CREDIT_CARD_NUMBER_PATTERN}
+ * - {@link EMAIL_ADDRESS_PATTERN}
+ * - {@link JWT_PATTERN}
+ * - {@link KR_RRN_PATTERN}
+ * - {@link US_SSN_PATTERN}
+ *
+ * @example
+ * ```ts
+ * import { defaultConsoleFormatter, getConsoleSink } from "@logtape/logtape";
+ * import {
+ *   CREDIT_CARD_NUMBER_PATTERN,
+ *   EMAIL_ADDRESS_PATTERN,
+ *   JWT_PATTERN,
+ *   redactByPattern,
+ * } from "@logtape/redaction";
+ *
+ * const formatter = redactByPattern(defaultConsoleFormatter, [
+ *   CREDIT_CARD_NUMBER_PATTERN,
+ *   EMAIL_ADDRESS_PATTERN,
+ *   JWT_PATTERN,
+ * ]);
+ * const sink = getConsoleSink({ formatter });
+ * ```
+ * @param formatter The console formatter to apply redaction to.
+ * @param patterns The redaction patterns to apply.
+ * @returns The redacted console formatter.
+ * @since 0.10.0
+ */
+export function redactByPattern(
+  formatter: ConsoleFormatter,
+  patterns: RedactionPatterns,
+): ConsoleFormatter;
+
+export function redactByPattern(
+  formatter: TextFormatter | ConsoleFormatter,
+  patterns: RedactionPatterns,
+): (record: LogRecord) => string | readonly unknown[] {
+  for (const { pattern } of patterns) {
+    if (!pattern.global) {
+      throw new TypeError(
+        `Pattern ${pattern} does not have the global flag set.`,
+      );
+    }
+  }
+
+  function replaceString(str: string): string {
+    for (const p of patterns) {
+      // The following ternary operator may seem strange, but it's for
+      // making TypeScript happy:
+      str = typeof p.replacement === "string"
+        ? str.replaceAll(p.pattern, p.replacement)
+        : str.replaceAll(p.pattern, p.replacement);
+    }
+    return str;
+  }
+
+  function replaceObject(object: unknown): unknown {
+    if (typeof object === "string") return replaceString(object);
+    else if (Array.isArray(object)) return object.map(replaceObject);
+    else if (typeof object === "object" && object !== null) {
+      // Check if object is a vanilla object:
+      if (
+        Object.getPrototypeOf(object) === Object.prototype ||
+        Object.getPrototypeOf(object) === null
+      ) {
+        const redacted: Record<string, unknown> = {};
+        for (const key in object) {
+          redacted[key] =
+            // @ts-ignore: object always has key
+            replaceObject(object[key]);
+        }
+        return redacted;
+      }
+    }
+    return object;
+  }
+
+  return (record: LogRecord) => {
+    const output = formatter(record);
+    if (typeof output === "string") return replaceString(output);
+    return output.map(replaceObject);
+  };
+}

package/tsdown.config.ts

@@ -0,0 +1,11 @@
+import { defineConfig } from "tsdown";
+
+export default defineConfig({
+  entry: "mod.ts",
+  dts: {
+    sourcemap: true,
+  },
+  format: ["esm", "cjs"],
+  platform: "neutral",
+  unbundle: true,
+});

package/esm/field.js

@@ -1,112 +0,0 @@
-/**
- * Default field patterns for redaction.  These patterns will match
- * common sensitive fields such as passwords, tokens, and personal
- * information.
- * @since 0.10.0
- */
-export const DEFAULT_REDACT_FIELDS = [
-    /pass(?:code|phrase|word)/i,
-    /secret/i,
-    /token/i,
-    /key/i,
-    /credential/i,
-    /auth/i,
-    /signature/i,
-    /sensitive/i,
-    /private/i,
-    /ssn/i,
-    /email/i,
-    /phone/i,
-    /address/i,
-];
-/**
- * Redacts properties in a {@link LogRecord} based on the provided field
- * patterns and action.
- *
- * Note that it is a decorator which wraps the sink and redacts properties
- * before passing them to the sink.
- *
- * @example
- * ```ts
- * import { getConsoleSink } from "@logtape/logtape";
- * import { redactByField } from "@logtape/redaction";
- *
- * const sink = redactByField(getConsoleSink());
- * ```
- *
- * @param sink The sink to wrap.
- * @param options The redaction options.
- * @returns The wrapped sink.
- * @since 0.10.0
- */
-export function redactByField(sink, options = DEFAULT_REDACT_FIELDS) {
-    const opts = Array.isArray(options) ? { fieldPatterns: options } : options;
-    const wrapped = (record) => {
-        sink({ ...record, properties: redactProperties(record.properties, opts) });
-    };
-    if (Symbol.dispose in sink)
-        wrapped[Symbol.dispose] = sink[Symbol.dispose];
-    if (Symbol.asyncDispose in sink) {
-        wrapped[Symbol.asyncDispose] = sink[Symbol.asyncDispose];
-    }
-    return wrapped;
-}
-/**
- * Redacts properties from an object based on specified field patterns.
- *
- * This function creates a shallow copy of the input object and applies
- * redaction rules to its properties. For properties that match the redaction
- * patterns, the function either removes them or transforms their values based
- * on the provided action.
- *
- * The redaction process is recursive and will be applied to nested objects
- * as well, allowing for deep redaction of sensitive data in complex object
- * structures.
- * @param properties The properties to redact.
- * @param options The redaction options.
- * @returns The redacted properties.
- * @since 0.10.0
- */
-export function redactProperties(properties, options) {
-    const copy = { ...properties };
-    for (const field in copy) {
-        if (shouldFieldRedacted(field, options.fieldPatterns)) {
-            if (options.action == null || options.action === "delete") {
-                delete copy[field];
-            }
-            else {
-                copy[field] = options.action(copy[field]);
-            }
-            continue;
-        }
-        const value = copy[field];
-        // Check if value is a vanilla object:
-        if (typeof value === "object" && value !== null &&
-            (Object.getPrototypeOf(value) === Object.prototype ||
-                Object.getPrototypeOf(value) === null)) {
-            // @ts-ignore: value is always Record<string, unknown>
-            copy[field] = redactProperties(value, options);
-        }
-    }
-    return copy;
-}
-/**
- * Checks if a field should be redacted based on the provided field patterns.
- * @param field The field name to check.
- * @param fieldPatterns The field patterns to match against.
- * @returns `true` if the field should be redacted, `false` otherwise.
- * @since 0.10.0
- */
-export function shouldFieldRedacted(field, fieldPatterns) {
-    for (const fieldPattern of fieldPatterns) {
-        if (typeof fieldPattern === "string") {
-            if (fieldPattern === field)
-                return true;
-        }
-        else {
-            if (fieldPattern.test(field))
-                return true;
-        }
-    }
-    return false;
-}

package/esm/mod.js

@@ -1,2 +0,0 @@
-export { DEFAULT_REDACT_FIELDS, redactByField, } from "./field.js";
-export * from "./pattern.js";

package/esm/package.json

@@ -1,3 +0,0 @@
-{
-  "type": "module"
-}