@beignet/core/dist/ports/redaction.d.ts

Core framework primitives for Beignet

/**
 * Default replacement used when a sensitive field is redacted.
 */
export declare const DEFAULT_REDACTED_VALUE = "[redacted]";
/**
 * Default replacement used when recursive redaction exceeds `maxDepth`.
 */
export declare const DEFAULT_TRUNCATED_VALUE = "[truncated]";
/**
 * Default replacement used when recursive redaction finds a circular object.
 */
export declare const DEFAULT_CIRCULAR_VALUE = "[circular]";
/**
 * Exact header/object keys redacted by default.
 */
export declare const DEFAULT_SENSITIVE_KEYS: readonly ["authorization", "proxy-authorization", "cookie", "set-cookie", "x-api-key", "api-key", "apikey", "access-token", "refresh-token", "credentials", "accesskey", "jwt", "session"];
/**
 * Key substrings redacted by default.
 *
 * Matching is case-insensitive.
 */
export declare const DEFAULT_SENSITIVE_KEY_TERMS: readonly ["token", "password", "secret", "credential", "accesskey", "jwt", "session", "private-key", "privatekey"];
/**
 * Context passed to custom redaction key decisions.
 */
export interface RedactionDecisionContext {
    /**
     * Current object/header key being evaluated.
     */
    key: string;
    /**
     * Path to the current value from the root object.
     */
    path: readonly string[];
    /**
     * Current value being evaluated.
     */
    value: unknown;
}
/**
 * Options that control recursive value and header redaction.
 */
export interface RedactionOptions {
    /**
     * Value used when a key is considered sensitive.
     */
    replacement?: string;
    /**
     * Value used when recursion exceeds `maxDepth`.
     */
    truncatedValue?: string;
    /**
     * Value used for circular references.
     */
    circularValue?: string;
    /**
     * Maximum object/array depth to traverse before truncating.
     */
    maxDepth?: number;
    /**
     * Additional exact keys to redact.
     */
    sensitiveKeys?: readonly string[];
    /**
     * Additional case-insensitive key substrings to redact.
     */
    sensitiveKeyTerms?: readonly string[];
    /**
     * Custom key-level redaction rule.
     */
    shouldRedactKey?: (context: RedactionDecisionContext) => boolean;
}
/**
 * Function that returns a redacted copy of a value.
 */
export type Redactor<T = unknown> = (value: T) => T;
/**
 * Header input shapes accepted by `redactHeaders(...)`.
 */
export type RedactableHeaders = Headers | Iterable<readonly [string, unknown]> | Record<string, unknown>;
/**
 * Return whether a key should be redacted.
 *
 * Checks default exact keys, default key terms, user-provided exact keys,
 * user-provided key terms, and finally `shouldRedactKey`.
 *
 * @param key - Object or header key to evaluate.
 * @param options - Optional redaction behavior.
 * @param context - Optional path/value context for custom decisions.
 * @returns `true` when the key should be replaced.
 */
export declare function isSensitiveKey(key: string, options?: RedactionOptions, context?: Omit<RedactionDecisionContext, "key">): boolean;
/**
 * Recursively redact a value using Beignet's default sensitive-key rules plus
 * any custom rules in `options`.
 *
 * This returns a copy for objects and arrays. Numbers and booleans are returned
 * as is unless they are under a sensitive key. High-confidence credential
 * shapes inside strings are replaced, including authorization schemes, JWTs,
 * credential-bearing URLs, secret assignments, and private keys. Some runtime
 * shapes are normalized:
 * `bigint` becomes a string, `Error` becomes a plain object with `name`,
 * `message`, and `stack`, and class instances are copied from enumerable
 * entries.
 *
 * @param value - Value to redact.
 * @param options - Optional redaction behavior.
 * @returns A redacted value typed as the input type for caller convenience.
 */
export declare function redactValue<T = unknown>(value: T, options?: RedactionOptions): T;
/**
 * Redact headers into a plain object.
 *
 * Sensitive header names such as `authorization`, `cookie`, and token-like keys
 * are replaced. Non-sensitive values are passed through `redactValue(...)` so
 * nested object values are still sanitized.
 *
 * @param headers - Headers object, iterable entries, or plain object.
 * @param options - Optional redaction behavior.
 * @returns A plain object with redacted header values.
 */
export declare function redactHeaders(headers: RedactableHeaders, options?: RedactionOptions): Record<string, unknown>;
/**
 * Create a reusable redactor function from options.
 *
 * @param options - Redaction behavior to apply on each call.
 * @returns A function that redacts values with the provided options.
 */
export declare function createRedactor<T = unknown>(options?: RedactionOptions): Redactor<T>;
//# sourceMappingURL=redaction.d.ts.map