@tallyrow/safesignal 1.0.1-rc.1

package/dist/types-D-xVvmvX.d.cts

@@ -0,0 +1,227 @@
+/**
+ * Public type surface for the frontend logging package.
+ *
+ * Every export here is part of the SemVer-stable consumer contract documented
+ * in `specs/001-structured-logging-core/contracts/`. Adding new optional
+ * fields is a minor-version change; removals or signature changes require a
+ * major-version bump and a migration note.
+ *
+ * Locked invariants:
+ *   - `Attributes` is a recursive **constrained** union — `unknown` and
+ *     `object` are deliberately excluded so passing a raw class instance is
+ *     type-friction. The sanitizer (T031) coerces stragglers at runtime.
+ *   - The ONLY `unknown` parameter in the public surface is the optional
+ *     `error` arg of `Logger.error()`.
+ *   - The package source MUST NOT consult any ambient state
+ *     (`process.env`, `import.meta.env`, `location`, `document.cookie`);
+ *     enforced by `tests/contract/no-ambient-state.test.ts` (T013).
+ *   - The public `.d.ts` MUST NOT mention `@opentelemetry/*` or any OTel
+ *     concept name; enforced by `tests/contract/declarations-surface.test.ts`
+ *     (T013) and `tests/security/bundle-shape.security.test.ts` (T049).
+ */
+/** Severity levels, in increasing order. */
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+/**
+ * Per-environment level overrides. Resolved per `contracts/logger-config.md`
+ * (LC-3): config.level (LevelMap → environment lookup) takes precedence over
+ * the env-default table.
+ */
+type LevelMap = Partial<Record<'production' | 'development' | 'test', LogLevel>>;
+/**
+ * A value that may appear inside `LogEvent.attributes` or
+ * `LogContext.attributes`. Excludes `unknown`, `object`, class instances, DOM
+ * nodes, framework objects, functions, symbols, and bigints by design —
+ * passing those is allowed at runtime (TypeScript cannot fully prevent it)
+ * but the sanitizer (T031) reduces them to type tags before any transport
+ * sees the event.
+ */
+type AttributeValue = string | number | boolean | null | AttributeValue[] | {
+    [key: string]: AttributeValue;
+};
+/** A bag of per-call or per-context structured attributes. Always an object. */
+type Attributes = Record<string, AttributeValue>;
+/** Application identity — the consuming app, even from a federated module. */
+interface AppIdentity {
+    name: string;
+    version?: string;
+}
+/** Module identity — for independently deployed federated modules. */
+interface ModuleIdentity {
+    name: string;
+    version?: string;
+}
+/**
+ * Merged context attached to every emitted `LogEvent`. Merge precedence
+ * is documented in `contracts/logger-config.md` (LC-7) and
+ * `data-model.md`: root config → per-logger options → logger chain
+ * (`child()` / `withContext()`) → `correlation()` return value.
+ */
+interface LogContext {
+    application?: AppIdentity;
+    module?: ModuleIdentity;
+    environment?: string;
+    attributes?: Attributes;
+}
+/**
+ * Captured error information populated by `Logger.error(msg, attrs, err)`.
+ * The pipeline reduces an arbitrary `unknown` error value to this shape
+ * immediately; transports never see the original `Error` instance.
+ */
+interface ErrorInfo {
+    name: string;
+    message: string;
+    stack?: string;
+}
+/**
+ * The canonical structured event produced by the pipeline. By the time a
+ * transport receives a `LogEvent`, it has been: (1) sanitized per
+ * `contracts/sanitization.md`, (2) URL-scrubbed, (3) redacted per
+ * `contracts/redaction.md` (fail-closed), (4) control-char-escaped, and
+ * (5) frozen in dev builds. See `contracts/log-event.md` LE-1..LE-11.
+ */
+interface LogEvent {
+    /** ISO-8601 string assigned by the pipeline; consumer-supplied input ignored. */
+    timestamp: string;
+    /** Severity matching the logger method called. */
+    level: LogLevel;
+    /** Required. Empty string allowed. Sanitized for length and control chars. */
+    message: string;
+    /** Always an object. May be empty. Sanitized and redacted before delivery. */
+    attributes: Attributes;
+    /** Always present. Merged from config + logger chain + correlation. */
+    context: LogContext;
+    /** Populated only when `Logger.error(msg, attrs, err)` is called with `err`. */
+    error?: ErrorInfo;
+}
+/**
+ * Delivery interface. Consumer transports MUST follow the security contract
+ * in `contracts/transport.md` (T-S1..T-S5): body-only delivery (POST/PUT
+ * JSON or `Blob` sendBeacon), HTTPS cross-origin, no event data in URL
+ * paths / queries / fragments, treat events as immutable, idempotent
+ * `flush`/`shutdown`. Failure isolation is provided by the package's
+ * internal `SafeTransport` wrapper.
+ */
+interface Transport {
+    /** Stable diagnostic identifier. */
+    name: string;
+    /** Receive a fully processed `LogEvent`. May be sync or async. */
+    send(event: LogEvent): void | Promise<void>;
+    /** Optional flush hook for batching transports. */
+    flush?(): Promise<void>;
+    /** Optional shutdown hook. Must be idempotent. */
+    shutdown?(): Promise<void>;
+}
+/**
+ * Factory that produces a `Transport`. Used by `LoggerConfig.transports`
+ * so configuration values can stay declarative — the factory is invoked
+ * once at `configureLogging()` time.
+ */
+type TransportFactory = () => Transport;
+/**
+ * One redaction rule. At least one of `key` or `shape` must be set.
+ *   - `key`: case-insensitive match against the IMMEDIATE property name of
+ *     the value being inspected (never a value substring).
+ *   - `shape`: match against leaf string values, regardless of key.
+ */
+interface RedactionRule {
+    key?: string | RegExp;
+    shape?: RegExp;
+    /** Replacement string. Default `'[REDACTED]'`. */
+    replacement?: string;
+}
+/**
+ * A redactor receives the post-sanitize, pre-control-char-guard `LogEvent`
+ * and returns either a transformed event or `null` to drop the event
+ * entirely. MUST be synchronous. If it throws or returns any other value,
+ * the dispatcher drops the event (fail-closed) and invokes
+ * `LoggerConfig.onInternalError`. See `contracts/redaction.md`.
+ */
+type Redactor = (event: LogEvent) => LogEvent | null;
+/**
+ * Configurable upper bounds for the sanitizer. Consumers MAY tighten any
+ * limit by passing a value below the default; values above the documented
+ * Max clamp to Max, values below Min clamp to Min, and both clamping events
+ * emit one `onInternalError` notice at `configureLogging()` time.
+ *
+ * Defaults / bounds (locked by `contracts/sanitization.md`):
+ *   maxDepth:           default  8, min  1, max     16
+ *   maxStringLength:    default  8192, min 64, max 65536
+ *   maxArrayLength:     default  1000, min  1, max 10000
+ *   maxAttributeCount:  default  256, min  1, max  4096
+ */
+interface SanitizerLimits {
+    maxDepth: number;
+    maxStringLength: number;
+    maxArrayLength: number;
+    maxAttributeCount: number;
+}
+/**
+ * Options for `scrubUrl(url, options?)`. The default URL scrubber strips
+ * query and (optionally) fragment params whose names match the redaction
+ * denylist; `extraParams` adds project-specific names.
+ */
+interface ScrubUrlOptions {
+    /** Additional query/fragment param names to scrub (case-insensitive). */
+    extraParams?: ReadonlyArray<string | RegExp>;
+    /** Whether to also scrub the URL fragment. Default `true`. */
+    fragment?: boolean;
+}
+/**
+ * Root logging configuration. Pass once via `configureLogging()`. Defaults
+ * are documented in `contracts/logger-config.md`.
+ */
+interface LoggerConfig {
+    application?: AppIdentity;
+    module?: ModuleIdentity;
+    /** `'production' | 'development' | 'test'` or any string; unknown → `warn`. */
+    environment?: string;
+    /** Single level or per-environment map. Overrides env defaults. */
+    level?: LogLevel | LevelMap;
+    /** Static metadata merged into every emitted event's context. */
+    context?: Partial<LogContext>;
+    /** Per-emit dynamic context hook. Must be cheap and synchronous. */
+    correlation?: () => Partial<LogContext>;
+    /** Configured transports. Empty/undefined installs `NoopTransport`. */
+    transports?: Array<Transport | TransportFactory>;
+    /** Custom redactor. Fully replaces the default unless composed manually. */
+    redactor?: Redactor;
+    /** Tighten sanitizer bounds. Values above documented Max are clamped. */
+    sanitizerLimits?: Partial<SanitizerLimits>;
+    /**
+     * Diagnostics hook for internal failures (transport throws, init failure,
+     * redactor throw, sanitizer-limit clamp). Fires at most once per
+     * failing transport per session.
+     */
+    onInternalError?: (err: Error) => void;
+}
+/**
+ * Options for `createLogger()` — layered on top of the root `LoggerConfig`.
+ */
+interface CreateLoggerOptions {
+    /** Optional free-form logger name for diagnostics. Not part of the event. */
+    name?: string;
+    /** Override `module` identity for this logger only (federated modules). */
+    module?: ModuleIdentity;
+    /** Additional static context for this logger. Merged with root context. */
+    context?: Partial<LogContext>;
+    /** Per-logger level override. Wins over root config and env defaults. */
+    level?: LogLevel;
+}
+/**
+ * The consumer-facing logger. Every method returns synchronously and never
+ * throws. The only `unknown` parameter in the public surface is the
+ * optional `error` arg of `error()`; the pipeline immediately reduces it
+ * to `ErrorInfo`.
+ */
+interface Logger {
+    debug(message: string, attributes?: Attributes): void;
+    info(message: string, attributes?: Attributes): void;
+    warn(message: string, attributes?: Attributes): void;
+    error(message: string, attributes?: Attributes, error?: unknown): void;
+    /** Return a derived logger with additional context layered on top. */
+    child(context: Partial<LogContext>): Logger;
+    /** Alias for `child()`. */
+    withContext(context: Partial<LogContext>): Logger;
+}
+
+export type { AppIdentity as A, CreateLoggerOptions as C, ErrorInfo as E, LevelMap as L, ModuleIdentity as M, RedactionRule as R, SanitizerLimits as S, Transport as T, AttributeValue as a, Attributes as b, LogContext as c, LogEvent as d, LogLevel as e, Logger as f, LoggerConfig as g, Redactor as h, ScrubUrlOptions as i, TransportFactory as j };

package/dist/types-D-xVvmvX.d.ts

@@ -0,0 +1,227 @@
+/**
+ * Public type surface for the frontend logging package.
+ *
+ * Every export here is part of the SemVer-stable consumer contract documented
+ * in `specs/001-structured-logging-core/contracts/`. Adding new optional
+ * fields is a minor-version change; removals or signature changes require a
+ * major-version bump and a migration note.
+ *
+ * Locked invariants:
+ *   - `Attributes` is a recursive **constrained** union — `unknown` and
+ *     `object` are deliberately excluded so passing a raw class instance is
+ *     type-friction. The sanitizer (T031) coerces stragglers at runtime.
+ *   - The ONLY `unknown` parameter in the public surface is the optional
+ *     `error` arg of `Logger.error()`.
+ *   - The package source MUST NOT consult any ambient state
+ *     (`process.env`, `import.meta.env`, `location`, `document.cookie`);
+ *     enforced by `tests/contract/no-ambient-state.test.ts` (T013).
+ *   - The public `.d.ts` MUST NOT mention `@opentelemetry/*` or any OTel
+ *     concept name; enforced by `tests/contract/declarations-surface.test.ts`
+ *     (T013) and `tests/security/bundle-shape.security.test.ts` (T049).
+ */
+/** Severity levels, in increasing order. */
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+/**
+ * Per-environment level overrides. Resolved per `contracts/logger-config.md`
+ * (LC-3): config.level (LevelMap → environment lookup) takes precedence over
+ * the env-default table.
+ */
+type LevelMap = Partial<Record<'production' | 'development' | 'test', LogLevel>>;
+/**
+ * A value that may appear inside `LogEvent.attributes` or
+ * `LogContext.attributes`. Excludes `unknown`, `object`, class instances, DOM
+ * nodes, framework objects, functions, symbols, and bigints by design —
+ * passing those is allowed at runtime (TypeScript cannot fully prevent it)
+ * but the sanitizer (T031) reduces them to type tags before any transport
+ * sees the event.
+ */
+type AttributeValue = string | number | boolean | null | AttributeValue[] | {
+    [key: string]: AttributeValue;
+};
+/** A bag of per-call or per-context structured attributes. Always an object. */
+type Attributes = Record<string, AttributeValue>;
+/** Application identity — the consuming app, even from a federated module. */
+interface AppIdentity {
+    name: string;
+    version?: string;
+}
+/** Module identity — for independently deployed federated modules. */
+interface ModuleIdentity {
+    name: string;
+    version?: string;
+}
+/**
+ * Merged context attached to every emitted `LogEvent`. Merge precedence
+ * is documented in `contracts/logger-config.md` (LC-7) and
+ * `data-model.md`: root config → per-logger options → logger chain
+ * (`child()` / `withContext()`) → `correlation()` return value.
+ */
+interface LogContext {
+    application?: AppIdentity;
+    module?: ModuleIdentity;
+    environment?: string;
+    attributes?: Attributes;
+}
+/**
+ * Captured error information populated by `Logger.error(msg, attrs, err)`.
+ * The pipeline reduces an arbitrary `unknown` error value to this shape
+ * immediately; transports never see the original `Error` instance.
+ */
+interface ErrorInfo {
+    name: string;
+    message: string;
+    stack?: string;
+}
+/**
+ * The canonical structured event produced by the pipeline. By the time a
+ * transport receives a `LogEvent`, it has been: (1) sanitized per
+ * `contracts/sanitization.md`, (2) URL-scrubbed, (3) redacted per
+ * `contracts/redaction.md` (fail-closed), (4) control-char-escaped, and
+ * (5) frozen in dev builds. See `contracts/log-event.md` LE-1..LE-11.
+ */
+interface LogEvent {
+    /** ISO-8601 string assigned by the pipeline; consumer-supplied input ignored. */
+    timestamp: string;
+    /** Severity matching the logger method called. */
+    level: LogLevel;
+    /** Required. Empty string allowed. Sanitized for length and control chars. */
+    message: string;
+    /** Always an object. May be empty. Sanitized and redacted before delivery. */
+    attributes: Attributes;
+    /** Always present. Merged from config + logger chain + correlation. */
+    context: LogContext;
+    /** Populated only when `Logger.error(msg, attrs, err)` is called with `err`. */
+    error?: ErrorInfo;
+}
+/**
+ * Delivery interface. Consumer transports MUST follow the security contract
+ * in `contracts/transport.md` (T-S1..T-S5): body-only delivery (POST/PUT
+ * JSON or `Blob` sendBeacon), HTTPS cross-origin, no event data in URL
+ * paths / queries / fragments, treat events as immutable, idempotent
+ * `flush`/`shutdown`. Failure isolation is provided by the package's
+ * internal `SafeTransport` wrapper.
+ */
+interface Transport {
+    /** Stable diagnostic identifier. */
+    name: string;
+    /** Receive a fully processed `LogEvent`. May be sync or async. */
+    send(event: LogEvent): void | Promise<void>;
+    /** Optional flush hook for batching transports. */
+    flush?(): Promise<void>;
+    /** Optional shutdown hook. Must be idempotent. */
+    shutdown?(): Promise<void>;
+}
+/**
+ * Factory that produces a `Transport`. Used by `LoggerConfig.transports`
+ * so configuration values can stay declarative — the factory is invoked
+ * once at `configureLogging()` time.
+ */
+type TransportFactory = () => Transport;
+/**
+ * One redaction rule. At least one of `key` or `shape` must be set.
+ *   - `key`: case-insensitive match against the IMMEDIATE property name of
+ *     the value being inspected (never a value substring).
+ *   - `shape`: match against leaf string values, regardless of key.
+ */
+interface RedactionRule {
+    key?: string | RegExp;
+    shape?: RegExp;
+    /** Replacement string. Default `'[REDACTED]'`. */
+    replacement?: string;
+}
+/**
+ * A redactor receives the post-sanitize, pre-control-char-guard `LogEvent`
+ * and returns either a transformed event or `null` to drop the event
+ * entirely. MUST be synchronous. If it throws or returns any other value,
+ * the dispatcher drops the event (fail-closed) and invokes
+ * `LoggerConfig.onInternalError`. See `contracts/redaction.md`.
+ */
+type Redactor = (event: LogEvent) => LogEvent | null;
+/**
+ * Configurable upper bounds for the sanitizer. Consumers MAY tighten any
+ * limit by passing a value below the default; values above the documented
+ * Max clamp to Max, values below Min clamp to Min, and both clamping events
+ * emit one `onInternalError` notice at `configureLogging()` time.
+ *
+ * Defaults / bounds (locked by `contracts/sanitization.md`):
+ *   maxDepth:           default  8, min  1, max     16
+ *   maxStringLength:    default  8192, min 64, max 65536
+ *   maxArrayLength:     default  1000, min  1, max 10000
+ *   maxAttributeCount:  default  256, min  1, max  4096
+ */
+interface SanitizerLimits {
+    maxDepth: number;
+    maxStringLength: number;
+    maxArrayLength: number;
+    maxAttributeCount: number;
+}
+/**
+ * Options for `scrubUrl(url, options?)`. The default URL scrubber strips
+ * query and (optionally) fragment params whose names match the redaction
+ * denylist; `extraParams` adds project-specific names.
+ */
+interface ScrubUrlOptions {
+    /** Additional query/fragment param names to scrub (case-insensitive). */
+    extraParams?: ReadonlyArray<string | RegExp>;
+    /** Whether to also scrub the URL fragment. Default `true`. */
+    fragment?: boolean;
+}
+/**
+ * Root logging configuration. Pass once via `configureLogging()`. Defaults
+ * are documented in `contracts/logger-config.md`.
+ */
+interface LoggerConfig {
+    application?: AppIdentity;
+    module?: ModuleIdentity;
+    /** `'production' | 'development' | 'test'` or any string; unknown → `warn`. */
+    environment?: string;
+    /** Single level or per-environment map. Overrides env defaults. */
+    level?: LogLevel | LevelMap;
+    /** Static metadata merged into every emitted event's context. */
+    context?: Partial<LogContext>;
+    /** Per-emit dynamic context hook. Must be cheap and synchronous. */
+    correlation?: () => Partial<LogContext>;
+    /** Configured transports. Empty/undefined installs `NoopTransport`. */
+    transports?: Array<Transport | TransportFactory>;
+    /** Custom redactor. Fully replaces the default unless composed manually. */
+    redactor?: Redactor;
+    /** Tighten sanitizer bounds. Values above documented Max are clamped. */
+    sanitizerLimits?: Partial<SanitizerLimits>;
+    /**
+     * Diagnostics hook for internal failures (transport throws, init failure,
+     * redactor throw, sanitizer-limit clamp). Fires at most once per
+     * failing transport per session.
+     */
+    onInternalError?: (err: Error) => void;
+}
+/**
+ * Options for `createLogger()` — layered on top of the root `LoggerConfig`.
+ */
+interface CreateLoggerOptions {
+    /** Optional free-form logger name for diagnostics. Not part of the event. */
+    name?: string;
+    /** Override `module` identity for this logger only (federated modules). */
+    module?: ModuleIdentity;
+    /** Additional static context for this logger. Merged with root context. */
+    context?: Partial<LogContext>;
+    /** Per-logger level override. Wins over root config and env defaults. */
+    level?: LogLevel;
+}
+/**
+ * The consumer-facing logger. Every method returns synchronously and never
+ * throws. The only `unknown` parameter in the public surface is the
+ * optional `error` arg of `error()`; the pipeline immediately reduces it
+ * to `ErrorInfo`.
+ */
+interface Logger {
+    debug(message: string, attributes?: Attributes): void;
+    info(message: string, attributes?: Attributes): void;
+    warn(message: string, attributes?: Attributes): void;
+    error(message: string, attributes?: Attributes, error?: unknown): void;
+    /** Return a derived logger with additional context layered on top. */
+    child(context: Partial<LogContext>): Logger;
+    /** Alias for `child()`. */
+    withContext(context: Partial<LogContext>): Logger;
+}
+
+export type { AppIdentity as A, CreateLoggerOptions as C, ErrorInfo as E, LevelMap as L, ModuleIdentity as M, RedactionRule as R, SanitizerLimits as S, Transport as T, AttributeValue as a, Attributes as b, LogContext as c, LogEvent as d, LogLevel as e, Logger as f, LoggerConfig as g, Redactor as h, ScrubUrlOptions as i, TransportFactory as j };

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "@tallyrow/safesignal",
+  "version": "1.0.1-rc.1",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "SafeSignal — secure structured logging facade and safety boundary for browser applications and federated frontend modules. Browser-first, vendor-neutral, secure-by-default sanitization, redaction, and pluggable transports.",
+  "license": "MIT",
+  "keywords": [
+    "safesignal",
+    "logging",
+    "structured-logging",
+    "browser",
+    "frontend",
+    "federated",
+    "module-federation",
+    "sanitization",
+    "redaction",
+    "transport",
+    "observability",
+    "secure-by-default"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitlab.com/tallyrow/safesignal.git"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "import": "./dist/testing.mjs",
+      "require": "./dist/testing.cjs"
+    },
+    "./transport-beacon": {
+      "types": "./dist/transport-beacon.d.ts",
+      "import": "./dist/transport-beacon.mjs",
+      "require": "./dist/transport-beacon.cjs"
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tests/tsconfig.json",
+    "typecheck:src": "tsc --noEmit",
+    "typecheck:tests": "tsc --noEmit -p tests/tsconfig.json",
+    "test": "vitest run",
+    "test:contract": "vitest run tests/contract",
+    "test:security": "vitest run tests/security",
+    "test:integration": "vitest run tests/integration",
+    "test:unit": "vitest run tests/unit",
+    "test:watch": "vitest"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/api-logs": "^0.57.0",
+    "@opentelemetry/sdk-logs": "^0.57.0",
+    "@types/node": "^20.0.0",
+    "@vitest/coverage-v8": "^2.1.0",
+    "happy-dom": "^15.0.0",
+    "tsup": "^8.3.0",
+    "typescript": "^5.4.0",
+    "vitest": "^2.1.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}