occlude

Deep-redact secrets and PII from any value before logging - by key name AND by value shape, logger-agnostic, returns a safe clone.

The problem

Access tokens, passwords, authorization headers, emails, and card numbers leak into logs and error reports constantly - usually because someone logged a whole request object or an error with a config field. Once a secret is in your log pipeline, it's a rotation-and-incident problem.

Current solutions fall short. Pino has redaction but it's pino-only and path-based - you must know the exact key path in advance. It cannot catch a JWT that shows up under an unexpected key, or a secret nested inside an array of unknown shape. General deep-clone-and-mask utilities exist but few combine value-shape detection with key-name heuristics and safe recursion.

Install

npm install occlude
# or
pnpm add occlude
# or
yarn add occlude

Use

import occlude from "occlude";

const safe = occlude({ password: "secret", user: "alice" });
// { password: "[REDACTED]", user: "alice" }

// Works with any logger
logger.info(occlude(request), "request received");

Real-world usage with HTTP request logging:

import occlude from "occlude";

app.use((req, res, next) => {
  logger.info({
    method: req.method,
    url: req.url,
    headers: occlude(req.headers), // Mask authorization headers
    body: occlude(req.body),         // Mask passwords, emails, tokens
  });
  next();
});

API

occlude(input, options?)

Deep-redact secrets and PII from any value before logging.

function occlude<T>(input: T, options?: OccludeOptions): T

Returns: A deep clone with matched values replaced by the mask. The input is never mutated.

Default key patterns (case-insensitive): password, passwd, pwd, secret, token, apikey, api_key, authorization, auth, cookie, set-cookie, sessionid, ssn, credit, card, cvv, pan, privatekey

Default value patterns (applied to string leaves):

• JWT tokens: three base64url segments separated by dots
• AWS access key ID: AKIA[0-9A-Z]{16}
• Email addresses
• Card numbers: 13-19 digits with optional separators

OccludeOptions

interface OccludeOptions {
  keys?: Rule[];            // Additional key rules (extends defaults)
  values?: RegExp[];        // Additional value rules (extends defaults)
  mask?: string | ((value: unknown) => string);   // Default: "[REDACTED]"
  depth?: number;           // Maximum recursion depth, default: 20
}

Rule types:

type Rule = string | RegExp | ((keyPath: string, value: unknown) => boolean);

Non-goals

occlude does NOT encrypt or tokenize data, provide reversible masking, integrate with specific loggers, or write to files or networks. It returns a safe clone for you to use with any logging system.

Composing with pino:

import pino from "pino";
import occlude from "occlude";

const logger = pino();

logger.info(occlude(sensitiveData));

Composing with winston:

import winston from "winston";
import occlude from "occlude";

const logger = winston.createLogger(...);

logger.log('info', occlude(sensitiveData));

TypeScript

occlude is written in TypeScript with full type definitions. All exports are properly typed:

import occlude, { type OccludeOptions, type Rule } from "occlude";

const options: OccludeOptions = {
  keys: [/custom/i],
  mask: (value) => `[MASKED: ${typeof value}]`,
};

const result = occlude(data, options);

Related Packages

Caching & Concurrency:

• @azghr/filterkit — Framework-agnostic, type-safe filtering for TypeScript
• @azghr/singlet — Deduplicate concurrent async calls
• staleness — Stale-while-revalidate caching for async functions

Text Processing:

• @azghr/shorn — Truncate strings by byte budget without breaking graphemes
• seriatim — Sequential processing utilities

HTTP & Network:

• forbear — Read server rate-limit instructions from HTTP responses
• forestall — Delay execution until a condition is met
• obviate — Render operations unnecessary through caching

System & Process:

• quiesce — Ordered, timeboxed graceful shutdown for Node
• sortition — Deterministic percentage rollouts and A/B bucketing
• stanch — Stop flows or operations based on conditions

Utilities:

• expunge — Remove or exclude items from collections
• placemark — Geographic location and mapping utilities
• specie — Currency and financial calculations

License

MIT