unnbound-logger-sdk 3.1.2 → 3.2.0

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+## [3.0.34](https://github.com/unnbounddev/unnbound-sdks/compare/unnbound-logger-sdk-v3.0.33...unnbound-logger-sdk-v3.0.34) (2025-11-25)
+
+
+### Bug Fixes
+
+* setup ci/cd ([dd2640f](https://github.com/unnbounddev/unnbound-sdks/commit/dd2640f01e39f1342f3e08dc882164b50331c7bb))
+
+## [3.0.33](https://github.com/unnbounddev/unnbound-sdks/compare/unnbound-logger-sdk-v3.0.32...unnbound-logger-sdk-v3.0.33) (2025-11-25)
+
+
+### Bug Fixes
+
+* setup ci/cd ([520c03a](https://github.com/unnbounddev/unnbound-sdks/commit/520c03aacd978d7923b3bcf45c4f74a870be019d))
+
+## [3.0.32](https://github.com/unnbounddev/unnbound-sdks/compare/unnbound-logger-sdk-v3.0.31...unnbound-logger-sdk-v3.0.32) (2025-11-25)
+
+
+### Bug Fixes
+
+* setup ci/cd ([d3759c1](https://github.com/unnbounddev/unnbound-sdks/commit/d3759c14f7863e4c8d2f5e80bdbbf2446df79f1a))
+* setup ci/cd ([7e06fc8](https://github.com/unnbounddev/unnbound-sdks/commit/7e06fc84ae7bafba3e9c2c0225f9f9d614fa9207))

package/README.md

@@ -148,6 +148,26 @@ logger.error({ err: new Error('Connection refused') }, 'Failed to sync order.');
 Errors are serialized by Pino's `stdSerializers.err`, which emits `type`, `message`, and `stack`.
 Unlike the other levels, `error` has no single-argument overload, so the message is required.
 
+### Redaction Masks
+
+`registerRedactionMasks` replaces each registered string with `[Redacted]` wherever it appears in a log line: messages, fields, errors, and child-logger bindings. `@ontemper/resources` registers the secrets it resolves; register other secret values yourself:
+
+```typescript
+import { logger, registerRedactionMasks } from 'unnbound-logger-sdk';
+
+registerRedactionMasks([apiKey]);
+const partnerLog = logger.child({ partner: 'acme', auth: `Bearer ${apiKey}` });
+partnerLog.info('Calling partner.');
+// Result: { ..., "partner": "acme", "auth": "Bearer [Redacted]", "message": "Calling partner." }
+```
+
+- Masks replace text in string values only. A property name that contains a secret is written unchanged.
+- Masks apply to the finished line when it is written. A mask registered after `child()` or `setBindings()` still redacts those bindings, and the output of custom serializers and formatters is masked too.
+- A mask registered inside a request scope applies to the whole scope, and stays active for the rest of the process after the scope ends. The process keeps at most 4096 of these retained masks and drops the oldest first; masks held by an active scope are not capped.
+- A value that code transforms before logging (for example, Base64-encodes) no longer matches its mask.
+
+Treat masking as a safeguard, not a guarantee: do not log secrets.
+
 ## HTTP Request/Response Logging
 
 ```typescript

package/dist/axios.d.ts

@@ -3,7 +3,10 @@ import { startSpan } from './span';
 import { type HttpOptions } from './types';
 type GetPayload = (config: AxiosRequestConfig, res?: AxiosResponse) => object;
 type RedactOptions = {
+    request?: boolean;
+    requestHeaders?: boolean;
     response?: boolean;
+    responseHeaders?: boolean;
 };
 export type OnRequest = (config: AxiosRequestConfig, callback: (config: AxiosRequestConfig) => Promise<AxiosResponse<any>>) => Promise<AxiosResponse<any>>;
 interface HttpClientOptions extends HttpOptions<GetPayload> {

package/dist/axios.js

@@ -16,25 +16,29 @@ const extractQueryParams = (url, config) => {
     keys.forEach((key) => object.searchParams.delete(key));
     return { url: object.toString(), query: keys.length > 0 ? query : undefined };
 };
-const buildOutgoingHttpPayload = (config, res, redact) => ({
-    type: 'http',
-    http: {
-        ...extractQueryParams(buildUrl(config.baseURL, config.url), config),
-        method: config.method?.toLowerCase() ?? 'get',
-        incoming: false,
-        request: {
-            headers: config.headers,
-            body: (0, utils_1.safeJsonParse)(config.data),
+const buildOutgoingHttpPayload = (config, res, redact) => {
+    const { url, query } = extractQueryParams(buildUrl(config.baseURL, config.url), config);
+    return {
+        type: 'http',
+        http: {
+            url,
+            query: redact?.request && query ? '[Redacted]' : query,
+            method: config.method?.toLowerCase() ?? 'get',
+            incoming: false,
+            request: {
+                headers: redact?.request || redact?.requestHeaders ? '[Redacted]' : config.headers,
+                body: redact?.request ? '[Redacted]' : (0, utils_1.safeJsonParse)(config.data),
+            },
+            response: res
+                ? {
+                    headers: redact?.response || redact?.responseHeaders ? '[Redacted]' : res.headers,
+                    status: res.status,
+                    body: redact?.response ? '[Redacted]' : (0, utils_1.safeJsonParse)(res.data),
+                }
+                : undefined,
         },
-        response: res
-            ? {
-                headers: res?.headers,
-                status: res.status,
-                body: redact?.response ? '[Redacted]' : (0, utils_1.safeJsonParse)(res.data),
-            }
-            : undefined,
-    },
-});
+    };
+};
 const getNoopPayload = () => ({});
 const onNoopRequest = (config, callback) => callback(config);
 const tracedMarker = Symbol.for('unnbound-logger-sdk.traceAxios.traced');
@@ -54,7 +58,9 @@ const traceAxios = (client, { ignoreTraceRoutes = types_1.defaultIgnoreTraceRout
 }) => {
     if (tracedMarker in client)
         return client;
-    const redact = redactOptions === true || redactOptions === false ? { response: redactOptions } : redactOptions;
+    const redact = redactOptions === true || redactOptions === false
+        ? { request: redactOptions, response: redactOptions }
+        : redactOptions;
     const createSpanWrappedRequest = (originalMethod, method) => {
         const { headers: defaultHeaders, ...partialDefaultConfig } = client.defaults;
         const headers = { ...defaultHeaders.common, ...(method && defaultHeaders[method]) };

package/dist/encode.d.ts

@@ -1,2 +1,7 @@
+/**
+ * Log records are read one line at a time — container stdout becomes one CloudWatch event per
+ * line and the log forwarder JSON-parses each event — so LF becomes CR to keep a value from
+ * splitting its own record. `whitespace-pre-wrap` still renders it as a break; `decode` restores LF.
+ */
 export declare const encode: (value: string) => string;
 export declare const decode: (value: string) => string;

package/dist/encode.js

@@ -1,7 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.decode = exports.encode = void 0;
-const encode = (value) => value.replaceAll('\n', '\r');
+const redaction_1 = require("./redaction");
+/**
+ * Log records are read one line at a time — container stdout becomes one CloudWatch event per
+ * line and the log forwarder JSON-parses each event — so LF becomes CR to keep a value from
+ * splitting its own record. `whitespace-pre-wrap` still renders it as a break; `decode` restores LF.
+ */
+const encode = (value) => (0, redaction_1.applyRedactionMasks)(value).replaceAll('\n', '\r');
 exports.encode = encode;
 const decode = (value) => value.replaceAll('\r', '\n');
 exports.decode = decode;

package/dist/index.d.ts

@@ -5,6 +5,7 @@ export { decode, encode } from './encode';
 export type { ILogger, UnnboundLogger } from './logger';
 export { logger } from './logger';
 export { traceMiddleware } from './middleware';
+export { applyRedactionMasks, registerRedactionMasks } from './redaction';
 export { startSpan } from './span';
 export type { UnnboundContext } from './storage';
 export { storage, withStorage } from './storage';

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.defaultTraceHeaderKey = exports.defaultMessageHeaderKey = exports.withTrace = exports.getTraceId = exports.withStorage = exports.storage = exports.startSpan = exports.traceMiddleware = exports.logger = exports.encode = exports.decode = exports.emitMetrics = exports.emitMetric = exports.traceAxios = void 0;
+exports.defaultTraceHeaderKey = exports.defaultMessageHeaderKey = exports.withTrace = exports.getTraceId = exports.withStorage = exports.storage = exports.startSpan = exports.registerRedactionMasks = exports.applyRedactionMasks = exports.traceMiddleware = exports.logger = exports.encode = exports.decode = exports.emitMetrics = exports.emitMetric = exports.traceAxios = void 0;
 var axios_1 = require("./axios");
 Object.defineProperty(exports, "traceAxios", { enumerable: true, get: function () { return axios_1.traceAxios; } });
 var emf_1 = require("./emf");
@@ -13,6 +13,9 @@ var logger_1 = require("./logger");
 Object.defineProperty(exports, "logger", { enumerable: true, get: function () { return logger_1.logger; } });
 var middleware_1 = require("./middleware");
 Object.defineProperty(exports, "traceMiddleware", { enumerable: true, get: function () { return middleware_1.traceMiddleware; } });
+var redaction_1 = require("./redaction");
+Object.defineProperty(exports, "applyRedactionMasks", { enumerable: true, get: function () { return redaction_1.applyRedactionMasks; } });
+Object.defineProperty(exports, "registerRedactionMasks", { enumerable: true, get: function () { return redaction_1.registerRedactionMasks; } });
 var span_1 = require("./span");
 Object.defineProperty(exports, "startSpan", { enumerable: true, get: function () { return span_1.startSpan; } });
 var storage_1 = require("./storage");

package/dist/logger.d.ts

@@ -1,5 +1,5 @@
 import pino from 'pino';
-import type { Bindings, DestinationStream } from 'pino';
+import type { Bindings, ChildLoggerOptions, DestinationStream } from 'pino';
 export interface ILogger {
     trace(object: Bindings, message: string): void;
     trace(message: string): void;
@@ -13,7 +13,8 @@ export interface ILogger {
         err: unknown;
     }>(object: O, message: string): void;
 }
-export interface UnnboundLogger extends ILogger, Omit<pino.Logger, keyof ILogger> {
+export interface UnnboundLogger extends ILogger, Omit<pino.Logger, keyof ILogger | 'child'> {
+    child(bindings: Bindings, options?: ChildLoggerOptions): UnnboundLogger;
 }
 export declare const createLogger: (destination?: DestinationStream) => UnnboundLogger;
 export declare const logger: UnnboundLogger;

package/dist/logger.js

@@ -8,6 +8,7 @@ const pino_1 = __importDefault(require("pino"));
 const uuid_1 = require("uuid");
 const encode_1 = require("./encode");
 const internal_1 = require("./internal");
+const redaction_1 = require("./redaction");
 const storage_1 = require("./storage");
 // The Temper name wins while legacy fallbacks keep existing workflow images compatible.
 const workflowEnvironment = process.env.TEMPER_ENVIRONMENT ??
@@ -25,15 +26,7 @@ const isStringAnnotation = (value) => {
         return false;
     }
 };
-const formatLog = (log, visited = new WeakSet()) => {
-    // Prevent infinite loops from circular references
-    if (visited.has(log))
-        return log;
-    visited.add(log);
-    // We can't encode frozen objects.
-    if (Object.isFrozen(log))
-        return log;
-    // We don't use Object.entries() for performance reasons
+const copyLogFields = (log, copy, copies, preserveErrorSerializer) => {
     for (const key in log) {
         if (!Object.hasOwn(log, key))
             continue;
@@ -42,23 +35,65 @@ const formatLog = (log, visited = new WeakSet()) => {
         if (key === '__proto__' || key === 'constructor' || key === 'prototype')
             continue;
         const value = log[key];
-        // We don't want to encode undefined values.
-        if (value === undefined)
-            continue;
-        // We can't encode immutable properties.
-        if (!Object.getOwnPropertyDescriptor(log, key)?.writable)
-            continue;
-        if (isStringAnnotation(value)) {
-            log[key] = (0, encode_1.encode)(value);
-        }
-        else if (Array.isArray(value)) {
-            log[key] = value.map((item) => isStringAnnotation(item) ? (0, encode_1.encode)(item) : isBindings(item) ? formatLog(item, visited) : item);
-        }
-        else if (isBindings(value)) {
-            log[key] = formatLog(value, visited);
+        if (value !== undefined) {
+            copy[key] =
+                preserveErrorSerializer && key === 'err' && value instanceof Error ? value : copyLogValue(value, copies);
         }
     }
-    return log;
+    return copy;
+};
+const copyLogValue = (value, copies) => {
+    if (isStringAnnotation(value))
+        return (0, encode_1.encode)(value);
+    if (Array.isArray(value)) {
+        const existing = copies.get(value);
+        if (Array.isArray(existing))
+            return existing;
+        const copy = [];
+        copies.set(value, copy);
+        for (const item of value)
+            copy.push(copyLogValue(item, copies));
+        return copy;
+    }
+    if (value instanceof Error) {
+        const serialized = pino_1.default.stdSerializers.err(value);
+        const copy = {};
+        copies.set(value, copy);
+        copies.set(serialized, copy);
+        return copyLogFields(serialized, copy, copies, false);
+    }
+    if (isBindings(value) && Object.prototype.toString.call(value) === '[object Object]') {
+        return copyBindings(value, copies, false);
+    }
+    // Class instances such as AxiosHeaders serialize through toJSON, so the copy walks that output.
+    if (isBindings(value) && value.toJSON instanceof Function) {
+        const existing = copies.get(value);
+        if (existing !== undefined)
+            return existing;
+        const copy = copyLogValue(value.toJSON(), copies);
+        copies.set(value, copy);
+        return copy;
+    }
+    return value;
+};
+const copyBindings = (log, copies, preserveErrorSerializer) => {
+    // Pino hands serializers whatever the caller passed; a primitive is not a WeakMap key.
+    if (!isBindings(log))
+        return log;
+    const existing = copies.get(log);
+    if (isBindings(existing))
+        return existing;
+    const copy = {};
+    copies.set(log, copy);
+    return copyLogFields(log, copy, copies, preserveErrorSerializer);
+};
+const formatLog = (log) => copyBindings(log, new WeakMap(), true);
+// `err` may be anything thrown; pino returns non-Error values unchanged, so only objects are copied.
+const formatError = (error) => {
+    const serialized = pino_1.default.stdSerializers.err(error);
+    if (isStringAnnotation(serialized))
+        return (0, encode_1.encode)(serialized);
+    return isBindings(serialized) ? formatLog(serialized) : serialized;
 };
 const loggerOptions = {
     level: process.env.LOG_LEVEL ?? 'debug',
@@ -73,14 +108,14 @@ const loggerOptions = {
     serializers: {
         req: pino_1.default.stdSerializers.req,
         res: pino_1.default.stdSerializers.res,
-        err: pino_1.default.stdSerializers.err,
+        err: formatError,
         message: encode_1.encode,
     },
     // Let CloudWatch handle timestamps
     timestamp: false,
     // Change message field from 'msg' to 'message'
     messageKey: 'message',
-    formatters: { level: formatLevel, log: formatLog },
+    formatters: { bindings: formatLog, level: formatLevel, log: formatLog },
     hooks: {
         logMethod(args, method) {
             const firstArg = args[0];
@@ -98,6 +133,8 @@ const loggerOptions = {
             }
             activeMethod.apply(this, args);
         },
+        // Masks registered after a value was serialized (child bindings, formatter output) still reach the line.
+        streamWrite: redaction_1.redactLogLine,
     },
     redact: {
         paths: [
@@ -105,12 +142,26 @@ const loggerOptions = {
             'http.response.headers.authorization',
             'http.request.headers.Authorization',
             'http.response.headers.Authorization',
+            // The EDI client presents its gateway credential in this header, so it joins
+            // the Authorization paths: request evidence keeps the URL/status, never the key.
+            'http.request.headers.ocp-apim-subscription-key',
+            'http.request.headers.Ocp-Apim-Subscription-Key',
             'err.config',
         ],
         remove: true,
     },
 };
-const createLogger = (destination) => destination ? (0, pino_1.default)(loggerOptions, destination) : (0, pino_1.default)(loggerOptions);
+// Pino children inherit the parent's own methods through Object.create, so every logger gets its own
+// wrappers bound to itself; otherwise a child's `child`/`setBindings` would act on its parent.
+const withRedaction = (instance, child, setBindings) => {
+    instance.child = (bindings, options) => withRedaction(child.call(instance, formatLog(bindings), options), child, setBindings);
+    instance.setBindings = (bindings) => setBindings.call(instance, formatLog(bindings));
+    return instance;
+};
+const createLogger = (destination) => {
+    const instance = destination ? (0, pino_1.default)(loggerOptions, destination) : (0, pino_1.default)(loggerOptions);
+    return withRedaction(instance, instance.child, instance.setBindings);
+};
 exports.createLogger = createLogger;
 exports.logger = (0, exports.createLogger)();
 process.on('uncaughtException', (err, origin) => {

package/dist/redaction.d.ts

@@ -0,0 +1,3 @@
+export declare function registerRedactionMasks(values: readonly string[]): void;
+export declare function applyRedactionMasks(value: string): string;
+export declare function redactLogLine(line: string): string;

package/dist/redaction.js

@@ -0,0 +1,135 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerRedactionMasks = registerRedactionMasks;
+exports.applyRedactionMasks = applyRedactionMasks;
+exports.redactLogLine = redactLogLine;
+const storage_1 = require("./storage");
+const REDACTED = '[Redacted]';
+function registerRedactionMasks(values) {
+    const masks = (0, storage_1.getRedactionMasks)() ?? storage_1.processRedactionMasks;
+    for (const value of values) {
+        if (value.length > 0)
+            masks.add(value);
+    }
+}
+const indexMasks = (masks) => {
+    const root = { edge: '', end: false, children: new Map() };
+    for (const mask of masks) {
+        let node = root;
+        let rest = mask;
+        while (rest.length > 0) {
+            const child = node.children.get(rest.charCodeAt(0));
+            if (!child) {
+                node.children.set(rest.charCodeAt(0), { edge: rest, end: true, children: new Map() });
+                rest = '';
+                node = root;
+                break;
+            }
+            let common = 1;
+            while (common < child.edge.length && child.edge.charCodeAt(common) === rest.charCodeAt(common))
+                common += 1;
+            if (common < child.edge.length) {
+                const tail = { edge: child.edge.slice(common), end: child.end, children: child.children };
+                child.edge = child.edge.slice(0, common);
+                child.end = false;
+                child.children = new Map([[tail.edge.charCodeAt(0), tail]]);
+            }
+            node = child;
+            rest = rest.slice(common);
+        }
+        if (node !== root)
+            node.end = true;
+    }
+    return root;
+};
+const jsonEscaped = (value) => JSON.stringify(value).slice(1, -1);
+// A written line holds each secret JSON-escaped, and `encode` may have turned LF into CR before serialization.
+const lineForms = (mask) => [jsonEscaped(mask), jsonEscaped(mask.replaceAll('\n', '\r'))];
+const indexes = new WeakMap();
+const indexOf = (masks) => {
+    const cached = indexes.get(masks);
+    if (cached?.version === masks.version)
+        return cached;
+    const line = indexMasks(new Set([...masks].flatMap(lineForms)));
+    const built = { version: masks.version, plain: indexMasks(masks), line };
+    indexes.set(masks, built);
+    return built;
+};
+const indexesInReach = (mode) => {
+    const scope = (0, storage_1.getRedactionMasks)();
+    const all = scope ? [storage_1.processRedactionMasks, scope] : [storage_1.processRedactionMasks];
+    return all.filter((masks) => masks.size > 0).map((masks) => indexOf(masks)[mode]);
+};
+const matchLength = (reach, value, cursor) => {
+    let longest = 0;
+    for (const root of reach) {
+        let position = cursor;
+        let node = root.children.get(value.charCodeAt(position));
+        while (node && value.startsWith(node.edge, position)) {
+            position += node.edge.length;
+            if (node.end && position - cursor > longest)
+                longest = position - cursor;
+            node = node.children.get(value.charCodeAt(position));
+        }
+    }
+    return longest;
+};
+// In a JSON line only string values are replaced, so property names, numbers, and delimiters keep the line
+// parseable, and the scan steps over whole escape sequences so a replacement never starts inside one.
+const replaceMasks = (value, reach, jsonLine) => {
+    if (reach.length === 0)
+        return value;
+    let redacted = '';
+    let copied = 0;
+    let cursor = 0;
+    let inString = !jsonLine;
+    let masking = !jsonLine;
+    const containers = [];
+    let expectKey = false;
+    while (cursor < value.length) {
+        const unit = value[cursor];
+        if (jsonLine && !inString) {
+            if (unit === '"') {
+                inString = true;
+                masking = !expectKey;
+            }
+            else if (unit === '{' || unit === '[') {
+                containers.push(unit);
+                expectKey = unit === '{';
+            }
+            else if (unit === '}' || unit === ']') {
+                containers.pop();
+            }
+            else if (unit === ',') {
+                expectKey = containers.at(-1) === '{';
+            }
+            else if (unit === ':') {
+                expectKey = false;
+            }
+            cursor += 1;
+            continue;
+        }
+        if (jsonLine && unit === '"') {
+            inString = false;
+            cursor += 1;
+            continue;
+        }
+        const length = masking ? matchLength(reach, value, cursor) : 0;
+        if (length > 0) {
+            redacted += value.slice(copied, cursor) + REDACTED;
+            cursor += length;
+            copied = cursor;
+            continue;
+        }
+        cursor += jsonLine && unit === '\\' ? (value[cursor + 1] === 'u' ? 6 : 2) : 1;
+    }
+    return copied === 0 ? value : redacted + value.slice(copied);
+};
+function applyRedactionMasks(value) {
+    return replaceMasks(value, indexesInReach('plain'), false);
+}
+// Masks the finished JSON line, so a mask registered after a child froze its bindings, or a value a serializer or
+// formatter produced, is still caught.
+function redactLogLine(line) {
+    return replaceMasks(line, indexesInReach('line'), true);
+}

package/dist/span.js

@@ -13,8 +13,7 @@ const startSpan = async (spanName, callback, getter) => {
     const spanId = (0, uuid_1.v4)();
     const start = performance.now();
     const previous = storage_1.storage.getStore();
-    return storage_1.storage.run({
-        ...previous,
+    return (0, storage_1.runWithStorage)({
         traceId: previous?.traceId ?? (0, trace_1.getTraceId)(),
         spanId: previous?.spanId ? `${spanId} ${previous?.spanId}` : spanId,
     }, async () => {

package/dist/storage.d.ts

@@ -4,9 +4,25 @@ export interface UnnboundContext {
     spanId?: string;
     messageId?: string;
 }
+/** Process-wide masks are bounded by count: the least recently registered secret is evicted first. */
+export declare const PROCESS_REDACTION_MASK_LIMIT = 4096;
+export declare class MaskSet extends Set<string> {
+    version: number;
+    add(mask: string): this;
+    delete(mask: string): boolean;
+    clear(): void;
+}
+declare class RecentMaskSet extends MaskSet {
+    private readonly limit;
+    constructor(limit: number);
+    add(mask: string): this;
+}
+export declare const processRedactionMasks: RecentMaskSet;
 interface UnnboundStorage extends AsyncLocalStorage<object> {
     getStore<T>(): T | undefined;
 }
 export declare const storage: UnnboundStorage;
+export declare const getRedactionMasks: () => MaskSet | undefined;
+export declare const runWithStorage: <T, Data extends object>(data: Data, callback: () => T) => T;
 export declare const withStorage: <T, Data extends object>(data: Data, callback: () => Promise<T>) => Promise<T>;
 export {};

package/dist/storage.js

@@ -1,12 +1,100 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.withStorage = exports.storage = void 0;
+exports.withStorage = exports.runWithStorage = exports.getRedactionMasks = exports.storage = exports.processRedactionMasks = exports.MaskSet = exports.PROCESS_REDACTION_MASK_LIMIT = void 0;
 const node_async_hooks_1 = require("node:async_hooks");
+const redactionMasksKey = Symbol('redactionMasks');
+/** Process-wide masks are bounded by count: the least recently registered secret is evicted first. */
+exports.PROCESS_REDACTION_MASK_LIMIT = 4096;
+// `version` changes only when membership does, so redaction rebuilds its mask index for a new or removed mask,
+// not when a re-registration moves an existing one to the newest position.
+class MaskSet extends Set {
+    version = 0;
+    add(mask) {
+        const present = Set.prototype.delete.call(this, mask);
+        Set.prototype.add.call(this, mask);
+        if (!present)
+            this.version += 1;
+        return this;
+    }
+    delete(mask) {
+        const removed = super.delete(mask);
+        if (removed)
+            this.version += 1;
+        return removed;
+    }
+    clear() {
+        this.version += 1;
+        super.clear();
+    }
+}
+exports.MaskSet = MaskSet;
+// Every resolver read re-registers its secrets, so one still being resolved stays resident while cold ones age out.
+class RecentMaskSet extends MaskSet {
+    limit;
+    constructor(limit) {
+        super();
+        this.limit = limit;
+    }
+    add(mask) {
+        super.add(mask);
+        if (this.size > this.limit) {
+            const oldest = this.values().next();
+            if (!oldest.done)
+                this.delete(oldest.value);
+        }
+        return this;
+    }
+}
+exports.processRedactionMasks = new RecentMaskSet(exports.PROCESS_REDACTION_MASK_LIMIT);
+// A root scope retains its masks once; detached work (a timer, an unawaited promise) that registers after that
+// point forwards to the process set for logs outside the scope, and keeps its own copy, which the cap cannot evict.
+class ScopeMasks extends MaskSet {
+    retained = false;
+    // Re-registration moves the mask to the end, so retention hands the process set the scope's masks by recency.
+    // A mask the process set already holds is refreshed there too: another trace may log it while this scope is open.
+    add(mask) {
+        if (this.retained || exports.processRedactionMasks.has(mask))
+            exports.processRedactionMasks.add(mask);
+        super.add(mask);
+        return this;
+    }
+}
 exports.storage = 
 // SAFETY: UnnboundStorage only adds a typed getStore helper over AsyncLocalStorage
 new node_async_hooks_1.AsyncLocalStorage();
-const withStorage = async (data, callback) => {
+const getRedactionMasks = () => exports.storage.getStore()?.[redactionMasksKey];
+exports.getRedactionMasks = getRedactionMasks;
+const retainMasks = (masks) => {
+    masks.retained = true;
+    for (const mask of masks)
+        exports.processRedactionMasks.add(mask);
+};
+// Nested scopes share the root's mask set; a root scope's secrets are returned and logged after it
+// exits, so its masks move to the process set on completion.
+const runWithStorage = (data, callback) => {
     const previous = exports.storage.getStore();
-    return exports.storage.run({ ...previous, ...data }, callback);
+    const inherited = previous?.[redactionMasksKey];
+    const masks = inherited ?? new ScopeMasks();
+    const context = { ...previous, ...data, [redactionMasksKey]: masks };
+    if (inherited)
+        return exports.storage.run(context, callback);
+    let result;
+    try {
+        result = exports.storage.run(context, callback);
+    }
+    catch (error) {
+        retainMasks(masks);
+        throw error;
+    }
+    if (result instanceof Promise) {
+        result.finally(() => retainMasks(masks)).catch(() => undefined);
+        return result;
+    }
+    retainMasks(masks);
+    return result;
+};
+exports.runWithStorage = runWithStorage;
+const withStorage = async (data, callback) => {
+    return (0, exports.runWithStorage)(data, callback);
 };
 exports.withStorage = withStorage;

package/dist/trace.js

@@ -13,6 +13,6 @@ const withTrace = (callback, extra) => {
     const previous = storage_1.storage.getStore();
     const traceId = extra?.traceId ?? previous?.traceId ?? (0, exports.getTraceId)();
     const messageId = extra?.messageId ?? previous?.messageId ?? (0, exports.getMessageId)();
-    return storage_1.storage.run({ ...previous, ...extra, traceId, messageId }, callback);
+    return (0, storage_1.runWithStorage)({ ...extra, traceId, messageId }, callback);
 };
 exports.withTrace = withTrace;

package/dist/types.d.ts

@@ -51,6 +51,7 @@ export interface SftpPayload {
     files?: string[];
     content?: string;
     exists?: string | false;
+    mode?: number | string;
 }
 export type EdiX12Operation = 'fromX12' | 'toX12' | 'validateX12' | 'acknowledgeX12';
 export type EdiOperation = EdiX12Operation;

package/dist/utils.d.ts

@@ -1,6 +1,10 @@
-/** patterns are globs (`*`, `?`) matched against the whole path. */
+/** patterns are globs (`*`, `?`) matched against the whole path; any other metacharacter is literal. */
 export declare const shouldIgnorePath: (path: string, patterns: string[]) => boolean;
+type ParsedJson = string | number | boolean | null | ParsedJson[] | {
+    [key: string]: ParsedJson;
+};
 /** Non-string or invalid JSON → input returned unchanged. */
-export declare function safeJsonParse(data: any): any;
+export declare function safeJsonParse<Body>(data: Body): Body | ParsedJson;
 /** Strips the IPv4-mapped IPv6 prefix (::ffff:). */
 export declare function normalizeIp(ip: string | undefined): string | undefined;
+export {};

package/dist/utils.js

@@ -3,10 +3,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.shouldIgnorePath = void 0;
 exports.safeJsonParse = safeJsonParse;
 exports.normalizeIp = normalizeIp;
-/** patterns are globs (`*`, `?`) matched against the whole path. */
+/** patterns are globs (`*`, `?`) matched against the whole path; any other metacharacter is literal. */
 const shouldIgnorePath = (path, patterns) => {
     return patterns.some((pattern) => {
-        const regexPattern = pattern.replace(/\./g, '\\.').replace(/\*/g, '.*').replace(/\?/g, '.');
+        const regexPattern = pattern.replace(/[.*+?^${}()|[\]\\]/g, (character) => character === '*' ? '.*' : character === '?' ? '.' : `\\${character}`);
         const regex = new RegExp(`^${regexPattern}$`);
         return regex.test(path);
     });
@@ -14,7 +14,7 @@ const shouldIgnorePath = (path, patterns) => {
 exports.shouldIgnorePath = shouldIgnorePath;
 /** Non-string or invalid JSON → input returned unchanged. */
 function safeJsonParse(data) {
-    if (String(data) === data) {
+    if (typeof data === 'string') {
         try {
             return JSON.parse(data);
         }

package/package.json

@@ -1,19 +1,9 @@
 {
   "name": "unnbound-logger-sdk",
   "description": "A structured logging library with TypeScript support using Pino. Provides consistent, well-typed logging with automatic logId, workflowId, traceId, and deploymentId tracking across operational contexts.",
-  "version": "3.1.2",
+  "version": "3.2.0",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
-  "scripts": {
-    "build": "tsc",
-    "test": "vitest run src",
-    "typecheck": "tsc --noEmit",
-    "format": "oxfmt --write .",
-    "format:check": "oxfmt --check .",
-    "prepublishOnly": "npm run build",
-    "start:example": "tsx watch examples/node-express.ts",
-    "version:bump": "npm version patch"
-  },
   "keywords": [
     "logging",
     "structured-logging",
@@ -66,5 +56,14 @@
   "engines": {
     "node": ">=22"
   },
-  "sideEffects": false
-}
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run src",
+    "typecheck": "tsc --noEmit",
+    "format": "oxfmt --write .",
+    "format:check": "oxfmt --check .",
+    "start:example": "tsx watch examples/node-express.ts",
+    "version:bump": "npm version patch"
+  }
+}