Reorganize repo structure and standards references

This commit is contained in:
david committed 2026-06-29 05:03:42 +02:00
1 parent 3cb93a81be
commit be2054274d
5885 files changed
+2588 -195

No files matched your search

@@ -0,0 +1,205 @@
/**
* 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
* `@toolctrl/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]`.
* - 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` 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 {
attributes?: Record<string, unknown> | undefined;
}
/**
* Structural shape of `SpanProcessor` from `@opentelemetry/sdk-trace-base`.
* Async `forceFlush()` / `shutdown()` are declared as `Promise<void>` 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<void>;
shutdown(): Promise<void>;
}
export const HEADER_ALLOWLIST: ReadonlySet<string> = new Set(
[
"content-type",
"user-agent",
"accept-language",
"accept-encoding",
"x-request-id",
"x-forwarded-for",
"referer",
].map((name) => name.toLowerCase()),
);
const QUERY_STRING_PLACEHOLDER = "?[scrubbed]";
const URL_LIKE_ATTRIBUTES = ["http.url", "http.target", "url.full", "url.path", "url.query"] 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]`. Returns the input unchanged when no `?` is present.
*/
export function scrubUrlQuery(value: string): string {
const queryIndex = value.indexOf("?");
if (queryIndex < 0) return value;
return `${value.slice(0, queryIndex)}${QUERY_STRING_PLACEHOLDER}`;
}
/**
* 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.<name>` and `http.response.header.<name>`
* 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<string, unknown> | 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] = scrubUrlQuery(value);
}
continue;
}
// Scrub SQL literals from db.statement.
if (key === "db.statement") {
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 {
try {
redactSpanAttributes(span.attributes);
} catch {
// Scrubber failures must never block the exporter chain; the span is
// forwarded as-is on the assumption the exporter will reject malformed
// payloads at its own layer.
}
this.delegate.onEnd(span);
}
forceFlush(): Promise<void> {
return this.delegate.forceFlush();
}
shutdown(): Promise<void> {
return this.delegate.shutdown();
}
}