/** * PII-scrubbing OpenTelemetry SpanProcessor. * * Decorator pattern: wraps an existing {@link SpanProcessor} (e.g. a * {@link BatchSpanProcessor}) and redacts sensitive span attributes during * `onEnd()` before delegating. The processor is structurally typed so that * `@hivegrid/observability` does not need to take a hard dependency on the * OpenTelemetry SDK packages — runtimes that already depend on * `@opentelemetry/sdk-trace-base` (api, worker, web) pass their `BatchSpanProcessor` * instances in directly. * * Scrubbing rules (see {@link redactSpanAttributes}): * - `http.url`, `http.target` and the OTel v1.20+ aliases `url.full`, * `url.path` get their query-string replaced with `?[scrubbed]`; fragments * are removed and `url.query` is redacted wholesale. Customer-portal * capability segments are redacted in URL attributes and span names. * - HTTP request/response headers are filtered through {@link HEADER_ALLOWLIST}. * Anything outside the allowlist (notably `authorization`, `cookie`, * `set-cookie`, `x-api-key`) is dropped. * - `db.statement` and `db.query.text` literal-string parameters (`'...'` * and `"..."`) are rewritten to `?` (defense-in-depth — Prisma already * parametrises). * - `messaging.message_payload` is dropped entirely; the payload-size * attribute (if present) is preserved. * * The processor MUST be registered BEFORE the exporter in the span-processor * chain — typically by wrapping the exporter's `BatchSpanProcessor`: * * ```ts * spanProcessors: [new PIISpanProcessor(new BatchSpanProcessor(otlpExporter))] * ``` */ /** * Structural shape of an OpenTelemetry span passed to a SpanProcessor. * Only the fields we mutate / read are typed here so we don't need to take * a runtime dependency on `@opentelemetry/sdk-trace-base`. */ export interface PiiScrubableSpan { name?: string | undefined; attributes?: Record | undefined; } /** * Structural shape of `SpanProcessor` from `@opentelemetry/sdk-trace-base`. * Async `forceFlush()` / `shutdown()` are declared as `Promise` here * to match the SDK shape exactly so a `BatchSpanProcessor` is assignable to * `DelegateSpanProcessor`. */ export interface DelegateSpanProcessor { onStart(span: PiiScrubableSpan, parentContext: unknown): void; onEnd(span: PiiScrubableSpan): void; forceFlush(): Promise; shutdown(): Promise; } export const HEADER_ALLOWLIST: ReadonlySet = new Set( [ "content-type", "user-agent", "accept-language", "accept-encoding", "x-request-id", ].map((name) => name.toLowerCase()), ); const QUERY_STRING_PLACEHOLDER = "?[scrubbed]"; const URL_LIKE_ATTRIBUTES = ["http.url", "http.target", "http.route", "url.full", "url.path", "url.query"] as const; const PORTAL_CAPABILITY_ROUTE_PATTERN = /((?:\/__portal)?\/[a-z0-9][a-z0-9-]{1,62}\/(?:login\/magic|setup|verify-email|reset-password)\/)[A-Za-z0-9_-]+/giu; const DB_STATEMENT_ATTRIBUTES = ["db.statement", "db.query.text"] as const; const DROP_ATTRIBUTES = ["messaging.message_payload"] as const; const HEADER_PREFIXES = ["http.request.header.", "http.response.header."] as const; /** * Strips the query-string from a URL-like attribute, replacing it with * `?[scrubbed]`, and redacts customer-portal capability path segments. */ export function scrubUrlQuery(value: string): string { const queryIndex = value.indexOf("?"); const fragmentIndex = value.indexOf("#"); if (queryIndex < 0 && fragmentIndex < 0) return redactPortalCapabilityTokens(value); if (queryIndex >= 0 && (fragmentIndex < 0 || queryIndex < fragmentIndex)) { return `${redactPortalCapabilityTokens(value.slice(0, queryIndex))}${QUERY_STRING_PLACEHOLDER}`; } return redactPortalCapabilityTokens(value.slice(0, fragmentIndex)); } /** Redacts customer-portal one-time credentials from span/transaction names. */ export function scrubSpanName(value: string): string { return scrubUrlQuery(value); } /** * Replaces all single-/double-quoted string literals in a SQL statement * with `?`. Used as defense-in-depth on top of Prisma's parameterisation. */ export function scrubDbStatement(statement: string): string { // Walk character-by-character so we handle escaped quotes and avoid // catastrophic backtracking on adversarial input. let out = ""; let i = 0; while (i < statement.length) { const ch = statement.charAt(i); if (ch === "'" || ch === '"') { const quote = ch; let j = i + 1; while (j < statement.length) { const inner = statement.charAt(j); if (inner === "\\" && j + 1 < statement.length) { j += 2; continue; } if (inner === quote) { break; } j += 1; } out += "?"; i = j + 1; continue; } out += ch; i += 1; } return out; } /** * Returns whether a span attribute key targets an HTTP header. * Both `http.request.header.` and `http.response.header.` * are matched (per OTel HTTP semantic conventions v1.20+). */ export function isHeaderAttribute(key: string): { isHeader: true; name: string } | { isHeader: false } { for (const prefix of HEADER_PREFIXES) { if (key.startsWith(prefix)) { return { isHeader: true, name: key.slice(prefix.length).toLowerCase() }; } } return { isHeader: false }; } /** * Mutates the given attribute bag in-place to apply the PII-scrubbing rules. * Exported for unit-tests so we can verify each rule independently of the * full SpanProcessor lifecycle. */ export function redactSpanAttributes(attributes: Record | undefined): void { if (!attributes) return; for (const key of Object.keys(attributes)) { // Drop disallowed attributes wholesale. if ((DROP_ATTRIBUTES as readonly string[]).includes(key)) { delete attributes[key]; continue; } // Strip query-strings from URL-like attributes. if ((URL_LIKE_ATTRIBUTES as readonly string[]).includes(key)) { const value = attributes[key]; if (typeof value === "string") { attributes[key] = key === "url.query" ? (value ? "[scrubbed]" : "") : scrubUrlQuery(value); } continue; } // Scrub SQL literals from current and legacy database statement fields. if ((DB_STATEMENT_ATTRIBUTES as readonly string[]).includes(key)) { const value = attributes[key]; if (typeof value === "string") { attributes[key] = scrubDbStatement(value); } continue; } // Allowlist-filter HTTP request/response headers. const header = isHeaderAttribute(key); if (header.isHeader) { if (!HEADER_ALLOWLIST.has(header.name)) { delete attributes[key]; } continue; } } } /** * Decorator SpanProcessor that scrubs PII from every ended span before * forwarding to a delegate (typically a `BatchSpanProcessor`). */ export class PIISpanProcessor implements DelegateSpanProcessor { constructor(private readonly delegate: DelegateSpanProcessor) {} onStart(span: PiiScrubableSpan, parentContext: unknown): void { this.delegate.onStart(span, parentContext); } onEnd(span: PiiScrubableSpan): void { if (!redactSpanName(span)) { return; } try { redactSpanAttributes(span.attributes); } catch { // Telemetry is optional; privacy is not. Replace the entire attribute bag // on scrubber failure, or drop the span when even that is impossible. try { span.attributes = {}; } catch { return; } } this.delegate.onEnd(span); } forceFlush(): Promise { return this.delegate.forceFlush(); } shutdown(): Promise { return this.delegate.shutdown(); } } function redactPortalCapabilityTokens(value: string): string { return value.replace(PORTAL_CAPABILITY_ROUTE_PATTERN, "$1redacted"); } function redactSpanName(span: PiiScrubableSpan): boolean { if (typeof span.name !== "string") return true; const sanitized = scrubSpanName(span.name); if (sanitized === span.name) return true; try { span.name = sanitized; return span.name === sanitized; } catch { // A credential-bearing immutable span name cannot be exported safely. return false; } }