@tallyrow/safesignal 1.0.1-rc.1

package/dist/index.d.ts

@@ -0,0 +1,167 @@
+import { g as LoggerConfig, C as CreateLoggerOptions, f as Logger, R as RedactionRule, h as Redactor, i as ScrubUrlOptions, j as TransportFactory } from './types-D-xVvmvX.js';
+export { A as AppIdentity, a as AttributeValue, b as Attributes, E as ErrorInfo, L as LevelMap, c as LogContext, d as LogEvent, e as LogLevel, M as ModuleIdentity, S as SanitizerLimits, T as Transport } from './types-D-xVvmvX.js';
+
+/**
+ * Public logger factories and root configuration flow.
+ *
+ *   - `configureLogging(config)` — install (or replace) the package's
+ *     module-scoped configuration. Atomic: the new runtime is built
+ *     and installed in a single slot swap, then the previously-active
+ *     runtime is torn down in the background so existing logger
+ *     references keep working without modification.
+ *   - `createLogger(options?)` — return a `Logger` whose context layers
+ *     on top of the current root configuration.
+ *   - `getRootLogger()` — singleton root logger created on first access.
+ *
+ * Behavior before `configureLogging()` is called is identical to a
+ * `configureLogging({})` invocation: env-unknown defaults (`warn`+),
+ * a single `NoopTransport`, and direct transport fan-out from the
+ * dispatcher. All emissions return synchronously and never throw.
+ *
+ * Vendor-neutrality: this module imports no observability-vendor SDK.
+ * The dispatcher fans sanitized + redacted events directly to the
+ * `SafeTransport`-wrapped consumer transports stored on the active
+ * `ConfiguredRuntime`. There is no telemetry backend in the v1
+ * default path; future vendor adapters are peer transports.
+ */
+
+/**
+ * Install or replace the package's configuration. Safe to call multiple
+ * times — the previous runtime's transports are flushed + shut down
+ * (fire-and-forget) and the new configuration is installed via an
+ * atomic active-runtime-slot swap, so existing logger references
+ * continue to work without re-acquisition.
+ *
+ * Per FR-031 / SC-012, the swap is observable to any subsequent emit
+ * from a retained `Logger` reference: emit reads through
+ * `getActiveRuntime()` at the time of the call, so the new runtime is
+ * live for the very next emission.
+ *
+ * Per FR-032 the call is the single explicit named API for installing
+ * a runtime. There is no implicit module-load side effect that
+ * replaces the runtime; only an explicit `configureLogging()`
+ * invocation can swap it.
+ */
+declare function configureLogging(config: LoggerConfig): void;
+/**
+ * Create a logger whose context layers on top of the current root
+ * configuration. The returned logger holds no captured state — every
+ * emission reads the *current* module-scoped configuration, so calling
+ * `configureLogging()` later affects loggers already created.
+ */
+declare function createLogger(options?: CreateLoggerOptions): Logger;
+/** Singleton root logger created on first access. */
+declare function getRootLogger(): Logger;
+
+/**
+ * Redactor — masks values whose **key** matches the default denylist
+ * (case-insensitive, immediate property name only, never a value
+ * substring) and values whose **shape** matches a documented sensitive
+ * pattern (JWT, Bearer-prefixed token). Runs in the pipeline AFTER the
+ * sanitizer and URL scrubber have normalized the event and BEFORE the
+ * control-char guard, freeze, and any transport.
+ *
+ * Contract: `contracts/redaction.md` (R-1..R-10).
+ *
+ * Two surfaces:
+ *   - `redact` (pipeline stage): wraps `config.redactor` (or the
+ *     default `createRedactor()` when not supplied), invokes it
+ *     synchronously, and enforces the fail-closed contract:
+ *       * If the redactor throws, the dispatcher's outer try/catch
+ *         drops the event and routes the throw to `onInternalError`.
+ *       * If the redactor returns `null`, the event is dropped (the
+ *         pipeline contract for explicit drop).
+ *       * If the redactor returns a value that is neither a LogEvent
+ *         nor `null`, this stage throws a `PackageError('redactor_failed')`
+ *         so the same fail-closed path applies.
+ *   - `createRedactor(rules?)` (public, re-exported from
+ *     `src/index.ts`): returns a `Redactor` configured with the
+ *     default rules when called with no argument, or with the
+ *     consumer's rule set (FULL replacement of defaults) when an
+ *     array is supplied. An empty array is a valid no-op rule set.
+ *
+ * Match semantics (per contract):
+ *   - **Key match**: a rule's `key` is tested against the immediate
+ *     property name being inspected. String keys match via case-
+ *     insensitive equality; RegExp keys match via `.test()`. A match
+ *     replaces the entire value (including object/array subtrees)
+ *     with `rule.replacement ?? '[REDACTED]'`. Recursion does not
+ *     descend into a value whose key matched — the whole subtree is
+ *     considered sensitive.
+ *   - **Shape match**: a rule's `shape` (RegExp) is tested against
+ *     leaf string values regardless of key context. A match replaces
+ *     the value with `rule.replacement ?? '[REDACTED]'`. Shape rules
+ *     do not match objects or arrays as containers — only leaf
+ *     strings.
+ *   - **Combination**: a rule with both `key` and `shape` matches
+ *     when either matches.
+ *
+ * Scope per field:
+ *   - `event.attributes` — recursive walk; key + shape rules apply.
+ *   - `event.context.attributes` — same recursive walk.
+ *   - `event.message` — string scan; shape rules only (no key context).
+ *   - `event.error.name`, `event.error.message`, `event.error.stack` —
+ *     string scan; shape rules only.
+ */
+
+declare function createRedactor(rules?: RedactionRule[]): Redactor;
+
+/**
+ * URL scrubber — strips sensitive query and fragment parameters from
+ * URL-shaped string values before any transport sees the event.
+ *
+ * Contract: `contracts/redaction.md` (URL-derived secrets) + plan.md
+ * "Security Architecture > URL scrubbing".
+ *
+ * Two surfaces:
+ *   - `urlScrub` (pipeline stage): walks `event.message`,
+ *     `event.attributes`, `event.context.attributes`, `event.error.*`
+ *     and rewrites any string that parses as an http(s) URL,
+ *     replacing sensitive query and (optionally) fragment param values
+ *     with `'[REDACTED]'`. Runs upstream of the redactor.
+ *   - `scrubUrl(url, options?)` (public helper, re-exported from
+ *     `src/index.ts`): the same operation surfaced directly so consumers
+ *     can pre-scrub URLs they want to log intentionally.
+ *
+ * Security invariants:
+ *   - NEVER throws. Malformed URLs, throwing getters on plain objects
+ *     (already collapsed by the sanitizer upstream), and pathological
+ *     fragments all fall through to "return input unchanged".
+ *   - Returns input unchanged for any string that is not a parseable
+ *     http(s) URL. Path segments, host, and authority are NOT modified
+ *     — only query and fragment parameter VALUES are replaced. Param
+ *     names are preserved.
+ *   - Operates on names (case-insensitive), never on value substrings —
+ *     the package never inspects a URL value's content for sensitive
+ *     shapes (that is the redactor's job, applied later in the pipeline).
+ */
+
+declare function scrubUrl(url: string, options?: ScrubUrlOptions): string;
+
+/**
+ * Built-in `ConsoleTransport`. Passes events to `console[level]` with the
+ * event message as the first argument and the **structured `LogEvent`
+ * object as the second argument** — never interpolated into a single
+ * string. Falls back to `console.log` only when `console[level]` is not a
+ * function (the modern browser console always defines all four levels).
+ *
+ * This is the only built-in delivery path that produces visible output.
+ * Console output preserves the structured-only invariant (FR-016, plan
+ * §Log-injection & output safety).
+ */
+
+declare const ConsoleTransport: TransportFactory;
+
+/**
+ * Built-in `NoopTransport`. Silently swallows every event.
+ *
+ * This is the automatic fallback when `LoggerConfig.transports` is
+ * undefined or empty (per `contracts/logger-config.md` LC default
+ * resolution). Useful in tests, in environments where logging is
+ * deliberately disabled, and as a placeholder during incremental
+ * configuration.
+ */
+
+declare const NoopTransport: TransportFactory;
+
+export { ConsoleTransport, CreateLoggerOptions, Logger, LoggerConfig, NoopTransport, RedactionRule, Redactor, ScrubUrlOptions, TransportFactory, configureLogging, createLogger, createRedactor, getRootLogger, scrubUrl };