@redact-secret/adapter-otel-trace 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,48 @@
+# Changelog
+
+All notable changes to `@redact-secret/adapter-otel-trace` are documented in
+this file. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+Every package in this repository carries its own SemVer and is released
+independently — see [ARCHITECTURE.md § Versioning](../../ARCHITECTURE.md#versioning).
+A change to the range this package declares against
+`@opentelemetry/sdk-trace-base` or against `@redact-secret/core` is always its
+own entry, naming the test that backs the new range, never folded into a
+generic "bump dependency" line.
+
+To release: in a PR into `develop`, move this section's `Unreleased`
+entries under a new `## [x.y.z] - YYYY-MM-DD` heading matching the version
+bumped in `package.json`. The next release train publishes and tags every
+package whose declared version isn't on its registry yet — see
+[RELEASING.md](../../RELEASING.md). This file ships inside the published
+tarball (`files` in `package.json`), so a consumer can read it from
+`node_modules` without leaving their editor.
+
+This package's code shipped as `@redact-secret/adapter-otel` `0.1.0` to
+`0.1.2`; that history is in
+[`packages/adapter-otel/CHANGELOG.md`](../adapter-otel/CHANGELOG.md). Its
+version numbers start again here, at `0.1.0`, and do not follow the old name's.
+
+## [Unreleased]
+
+## [0.1.0] - 2026-09-30
+### Added
+
+- The package, under a name that says what it covers: OpenTelemetry JS
+  **traces** (redact-secret/redact-secret-adapters#49). It is the code
+  `@redact-secret/adapter-otel` `0.1.2` shipped, unchanged: the same
+  `createRedactingSpanProcessor`, `RedactingSpanProcessorWith`,
+  `redactAttributesWith`, options (`policy`, `maxStringLength`, `onOutcome`,
+  and `pii` on the live factory) and outcome shape, and the same
+  `REDACT_SECRET_SPAN_DROPPED` warning, whose message still begins
+  `@redact-secret/adapter-otel:` so a filter written against it keeps
+  matching. It protects spans only — the span name, attributes, events, status
+  message and link attributes. OpenTelemetry Logs (`LogRecord`s) pass through
+  no code in this package.
+- Declares `@opentelemetry/sdk-trace-base` `^2.0.0` and `@redact-secret/core`
+  `^0.1.0-beta.6`, the ranges `adapter-otel` `0.1.2` declared, backed by the
+  same real-host tests (`test/otel-host.test.ts`, `test/otel-lifecycle.test.ts`,
+  `test/outcome.test.ts`, `test/vault-token.test.ts`), which CI runs at both
+  ends of each range. `test/exporter-bytes.test.ts` adds the final OTLP JSON
+  bytes an exporter would send, for the injected and the live factory, through
+  both `SimpleSpanProcessor` and `BatchSpanProcessor`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Omiologic
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,218 @@
+# @redact-secret/adapter-otel-trace
+
+A redacting OpenTelemetry JS `SpanProcessor` for **traces**, over the
+[Redact Secret](https://github.com/redact-secret/redact-secret) core.
+
+```js
+import { NodeTracerProvider, BatchSpanProcessor } from "@opentelemetry/sdk-trace-node";
+import { createRedactingSpanProcessor } from "@redact-secret/adapter-otel-trace";
+
+const provider = new NodeTracerProvider({
+  spanProcessors: [await createRedactingSpanProcessor(new BatchSpanProcessor(exporter))],
+});
+```
+
+## What it covers, and what it does not
+
+**Spans only.** This package plugs into the tracing pipeline and sees what a
+`SpanProcessor` sees. It does **not** protect OpenTelemetry **Logs**: a
+`LogRecord` emitted through `@opentelemetry/sdk-logs` (or a log bridge such as
+the pino or winston instrumentation) never passes through it and reaches its
+exporter as it was written. There is no OpenTelemetry Logs adapter yet;
+`@redact-secret/adapter-otel-logs` is a reserved name for one, not a package.
+Metrics are not covered either.
+
+This package was published as
+[`@redact-secret/adapter-otel`](https://www.npmjs.com/package/@redact-secret/adapter-otel) up to `0.1.2`. That name keeps working — its
+releases after `0.1.2` re-export this package — but new code should import
+from here; see
+[Migrating from `@redact-secret/adapter-otel`](#migrating-from-redact-secretadapter-otel).
+
+<!-- smoke-test:example -->
+```js
+import { BasicTracerProvider, SimpleSpanProcessor } from "@opentelemetry/sdk-trace-base";
+import { JsonTraceSerializer } from "@opentelemetry/otlp-transformer";
+import { createRedactingSpanProcessor } from "@redact-secret/adapter-otel-trace";
+
+// Synthetic, revoked-shaped values only — never a real credential.
+const token = "ghp_SYNTHETICREVOKED00000000000000000000";
+
+// Writes the OTLP/JSON request body an OTLP http/json exporter would send.
+const exporter = {
+  export(spans, done) {
+    process.stdout.write(`${new TextDecoder().decode(JsonTraceSerializer.serializeRequest(spans))}\n`);
+    done({ code: 0 });
+  },
+  shutdown: async () => {},
+};
+
+const provider = new BasicTracerProvider({
+  spanProcessors: [await createRedactingSpanProcessor(new SimpleSpanProcessor(exporter))],
+});
+const span = provider.getTracer("checkout").startSpan(`deploy ${token}`);
+span.setAttribute("llm.input_messages", `deploy with token ${token}`);
+span.addEvent("tool_call", { "tool.args": `Bearer ${token}` });
+span.end();
+await provider.shutdown();
+// ...{"name":"deploy <SECRET_1>",...,"attributes":[{"key":"llm.input_messages","value":{"stringValue":"deploy with token <SECRET_1>"}}],...
+```
+
+The clean-install smoke test (`npm run smoke-test`) runs this block verbatim
+from a throwaway project outside the repository, against the real core, and
+inspects the exporter's bytes.
+
+## What is redacted
+
+In `onEnd`, before the span reaches the next processor, the processor redacts
+the span name, every string and string-array attribute (a `null` hole in an
+array is kept in place), every event's name and attributes, the status message,
+and every link's attributes. Attribute names are not
+allowlisted, so OpenInference (`llm.input_messages`, `input.value`, …) and GenAI
+semantic-convention attributes (`gen_ai.prompt`, …) are covered without
+hardcoding either convention.
+
+## The load-bearing assumption
+
+`ReadableSpan`'s fields are typed `readonly` but are plain writable objects at
+runtime, and this processor writes the masked values back in place. Every write
+is read back; if one does not take (for example, an earlier processor froze the
+attributes), the span is **dropped** — not exported, and nothing is thrown out
+of `span.end()` — and a one-time process warning
+(`REDACT_SECRET_SPAN_DROPPED`) names the field, never its value.
+`test/otel-host.test.ts` builds a real span, passes it through a real
+`BasicTracerProvider`, and asserts the exporter saw redacted fields. That
+assertion is not optional.
+
+## Exports
+
+| Export | Purpose |
+| --- | --- |
+| `createRedactingSpanProcessor(next, options?)` | Live: awaits the core's `initialize()`, wraps `next` |
+| `RedactingSpanProcessorWith` | `new (next, scanAndRedact, options?)` — injected scanner |
+| `redactAttributesWith(scanAndRedact, attributes, options?)` | Mutates one attribute bag in place; throws a `TypeError` (naming no value) if it cannot |
+
+`options` is `{ policy, maxStringLength }` — `MaskLeafOptions`, re-exported
+here — plus `onOutcome` and, on the live factory, `pii` — every option
+`adapter-otel` `0.1.2` had. The older `RedactAttributesOptions` alias is deprecated. See
+[`@redact-secret/adapter`](../adapter#fail-closed-markers) for the markers.
+
+**Attribute names are not scanned.** The processor masks attribute *values*
+(and the span name, event names, and status message). Every attribute key,
+on the span, its events, and its links, reaches the exporter unchanged, so an
+attribute *named* after a secret keeps that name. Do not put a secret in an
+attribute key.
+
+## PII detection is opt-in
+
+The core detects credentials out of the box; PII detection is a
+separate activation, and it is process-wide and one-shot — the first selection
+wins, and a later *different* one fails with `PII_ACTIVATION_CONFLICT`.
+
+Either order works. Activate it yourself before building the provider:
+
+```js
+await initialize({ pii: ["pii:global"] });
+const processor = await createRedactingSpanProcessor(next); // accepted, not fought over
+```
+
+or let the factory do it, which is the order to prefer when this adapter is the
+first thing in the process to touch the core:
+
+```js
+const processor = await createRedactingSpanProcessor(next, { pii: ["pii:global"] });
+```
+
+When you pass `pii`, the factory reads the core's `piiActivation()` afterwards
+and **rejects** if the active selection is not the one you asked for, rather
+than returning a processor that scans with PII silently off. The rejection
+carries a fixed `code` — `PII_ACTIVATION_NOT_ACTIVE`, or
+`PII_ACTIVATION_UNSUPPORTED` against a core too old to report an activation —
+and never echoes a selector, the input, or the core's own message. Omitting
+`pii` needs no newer core: the declared `@redact-secret/core` range is
+unchanged, and every other initialization failure still rejects exactly as it
+did.
+
+**Activation is not masking.** Under the core's default policy, PII types are
+confidence-gated rather than always redacted: a `High`-confidence finding
+redacts, while `Medium` and `Low` resolve to `warn` — and a `warn` finding
+leaves the text alone. Enabling PII therefore still lets lower-confidence PII
+reach the exporter as plaintext. Pass your own `policy` mapping those findings
+to `redact` if you need them masked; this package decides nothing about policy.
+The counters below make it visible: a span whose `values.findings` is non-zero
+while `values.redacted` stays at zero is exactly this case.
+
+## Counting what happened
+
+`onOutcome` reports one summary per **span**. It is
+observational: increment your own counters from it. This package creates no
+exporter or network client for you.
+
+```js
+const processor = await createRedactingSpanProcessor(new BatchSpanProcessor(exporter), {
+  onOutcome: ({ values, dropped }) => {
+    metrics.increment("span.redacted_values", values.redacted);
+    if (dropped) metrics.increment("span.dropped_unredactable");
+  },
+});
+```
+
+```text
+{ host: "otel", unit: "span",
+  values: { scanned, findings, redacted, blocked, limited, failed },
+  dropped: false }
+```
+
+The counts are defined in
+[`@redact-secret/adapter`](../adapter#outcome-counters) — `findings` is not a
+count of distinct credentials, and `redacted` is lower than `findings` whenever
+a finding leaves text alone. Every string attribute, array element, event name
+and status message is its own counted leaf; attribute *names* are not scanned
+and not counted.
+
+`dropped` is **this processor's** decision: it did not hand the span to the
+next processor because a masked value would not write back (see the
+load-bearing assumption above). It does not mean the span was sampled out, and
+`dropped: false` does **not** mean the span was exported — whether the next
+processor kept it and whether an exporter succeeded are things this adapter
+never learns and does not report.
+
+- The observer runs once the span has been forwarded or dropped, so it cannot
+  change what is exported, and anything it throws is swallowed and never read.
+- It is re-entrancy- and thread-guarded: an observer that ends another span
+  does not recurse, and one thread's report never suppresses another's.
+
+## Supported SDK versions
+
+`@opentelemetry/sdk-trace-base ^2.0.0` and `@redact-secret/core`
+`^0.1.0-beta.6`. CI runs the real-host tests at both ends of each range. The
+SDK is imported as types only — it never enters this package's runtime graph.
+
+## Migrating from `@redact-secret/adapter-otel`
+
+`0.1.0` of this package is the code `@redact-secret/adapter-otel` `0.1.2`
+shipped: the same exports, options, outcome shape, peer ranges and fail-closed
+markers. Only the name changes, so migrating is a dependency swap and an import
+specifier:
+
+```sh
+npm uninstall @redact-secret/adapter-otel
+npm install @redact-secret/adapter-otel-trace
+```
+
+```diff
+-import { createRedactingSpanProcessor } from "@redact-secret/adapter-otel";
++import { createRedactingSpanProcessor } from "@redact-secret/adapter-otel-trace";
+```
+
+Nothing breaks if you do not migrate yet. `@redact-secret/adapter-otel`
+`0.1.2` is this code under the old name, and its later releases re-export this
+package, so both names hand out the same functions and the same
+`RedactingSpanProcessorWith` class and mixing them in one process is safe.
+Those later releases mark every export `@deprecated`, which editors show as a
+strikethrough.
+
+Neither name protects OpenTelemetry Logs, before or after migrating.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The live OpenTelemetry JS **trace** integration: a `SpanProcessor`. It does
+ * not see OpenTelemetry Logs (`LogRecord`s); nothing in this package protects
+ * them. It was published as `@redact-secret/adapter-otel` up to `0.1.2`; that
+ * name now re-exports this package.
+ *
+ * ```js
+ * import { NodeTracerProvider, BatchSpanProcessor } from "@opentelemetry/sdk-trace-node";
+ * import { createRedactingSpanProcessor } from "@redact-secret/adapter-otel-trace";
+ *
+ * const provider = new NodeTracerProvider({
+ *   spanProcessors: [await createRedactingSpanProcessor(new BatchSpanProcessor(exporter))],
+ * });
+ * ```
+ *
+ * `await initialize()` must resolve before `scanAndRedact` is used; this
+ * factory enforces that order. It is the only code in the package that loads
+ * `@redact-secret/core` at runtime, and does so on call (as
+ * `@redact-secret/adapter`'s `createMaskSecrets` does), so importing the
+ * injected API never loads the native core.
+ *
+ * PII detection is opt-in and process-wide in the core. Omit `pii` and this
+ * factory initializes the core as before and accepts whatever selection the
+ * application already activated, in either order. Pass
+ * `createRedactingSpanProcessor(next, { pii: ["pii:global"] })` to activate a
+ * selection from here instead, and the factory rejects rather than run with
+ * PII off. See `@redact-secret/adapter`'s `activateCore` for the whole rule,
+ * including why activation is not the same as masking every PII value.
+ */
+import type { SpanProcessor } from "@opentelemetry/sdk-trace-base";
+import { type CoreActivation } from "@redact-secret/adapter";
+import { type RedactingSpanProcessorOptions, RedactingSpanProcessorWith } from "./span-processor.js";
+export type { CoreActivation, MaskLeafOptions } from "@redact-secret/adapter";
+export { type OtelSpanOutcome, type RedactAttributesOptions, type RedactingSpanProcessorOptions, RedactingSpanProcessorWith, redactAttributesWith, } from "./span-processor.js";
+/** {@link RedactingSpanProcessorOptions} plus the live factory's PII activation. */
+export type CreateRedactingSpanProcessorOptions = RedactingSpanProcessorOptions & CoreActivation;
+/**
+ * Awaits `initialize()` once, then wraps `next` with the real scanner.
+ * `options.onOutcome` reports one input-free summary per span.
+ *
+ * `options.pii` activates core PII selectors for the whole process. Omit it
+ * and an activation the application already made is accepted rather than
+ * fought over. Pass it and this rejects — with a fixed message and code, never
+ * a selector or a core message — rather than run with PII off.
+ */
+export declare function createRedactingSpanProcessor(next: SpanProcessor, options?: CreateRedactingSpanProcessorOptions): Promise<RedactingSpanProcessorWith>;

package/dist/index.js

@@ -0,0 +1,50 @@
+/**
+ * The live OpenTelemetry JS **trace** integration: a `SpanProcessor`. It does
+ * not see OpenTelemetry Logs (`LogRecord`s); nothing in this package protects
+ * them. It was published as `@redact-secret/adapter-otel` up to `0.1.2`; that
+ * name now re-exports this package.
+ *
+ * ```js
+ * import { NodeTracerProvider, BatchSpanProcessor } from "@opentelemetry/sdk-trace-node";
+ * import { createRedactingSpanProcessor } from "@redact-secret/adapter-otel-trace";
+ *
+ * const provider = new NodeTracerProvider({
+ *   spanProcessors: [await createRedactingSpanProcessor(new BatchSpanProcessor(exporter))],
+ * });
+ * ```
+ *
+ * `await initialize()` must resolve before `scanAndRedact` is used; this
+ * factory enforces that order. It is the only code in the package that loads
+ * `@redact-secret/core` at runtime, and does so on call (as
+ * `@redact-secret/adapter`'s `createMaskSecrets` does), so importing the
+ * injected API never loads the native core.
+ *
+ * PII detection is opt-in and process-wide in the core. Omit `pii` and this
+ * factory initializes the core as before and accepts whatever selection the
+ * application already activated, in either order. Pass
+ * `createRedactingSpanProcessor(next, { pii: ["pii:global"] })` to activate a
+ * selection from here instead, and the factory rejects rather than run with
+ * PII off. See `@redact-secret/adapter`'s `activateCore` for the whole rule,
+ * including why activation is not the same as masking every PII value.
+ */
+import { activateCore } from "@redact-secret/adapter";
+import { RedactingSpanProcessorWith } from "./span-processor.js";
+export { RedactingSpanProcessorWith, redactAttributesWith, } from "./span-processor.js";
+/**
+ * Awaits `initialize()` once, then wraps `next` with the real scanner.
+ * `options.onOutcome` reports one input-free summary per span.
+ *
+ * `options.pii` activates core PII selectors for the whole process. Omit it
+ * and an activation the application already made is accepted rather than
+ * fought over. Pass it and this rejects — with a fixed message and code, never
+ * a selector or a core message — rather than run with PII off.
+ */
+export async function createRedactingSpanProcessor(next, options = {}) {
+    // `pii` is read by property so an inherited activation survives, and
+    // `options` is forwarded as the same object so every other inherited key
+    // does too. `pii` rides along unread, as any unknown key would.
+    const activation = options.pii === undefined ? {} : { pii: options.pii };
+    const loaded = await import("@redact-secret/core");
+    await activateCore(loaded, activation);
+    return new RedactingSpanProcessorWith(next, loaded.scanAndRedact, options);
+}

package/dist/span-processor.d.ts

@@ -0,0 +1,92 @@
+/**
+ * A `SpanProcessor` (OpenTelemetry JS, pinned against
+ * `@opentelemetry/sdk-trace-base@2.11.0`:
+ * https://github.com/open-telemetry/opentelemetry-js/blob/main/packages/sdk-trace/src/SpanProcessor.ts)
+ * that redacts the span name, every string and string-array attribute —
+ * including OpenInference (`llm.input_messages`, `input.value`, ...) and
+ * GenAI semantic-convention attributes (`gen_ai.prompt`, ...) — each event's
+ * name and attributes, the status message, and each link's attributes,
+ * before handing the span to the next processor. It does not
+ * allowlist those attribute names: every string-shaped attribute value is
+ * scanned, which covers any semantic convention without hardcoding it and
+ * without a dependency on either convention's attribute list.
+ *
+ * `ReadableSpan`'s fields are typed `readonly` but are plain, writable
+ * objects at runtime, and `onEnd` writes the masked values back in place.
+ * Every write is read back. If one does not take (a frozen bag, a setter
+ * that ignores it), the span is dropped — never forwarded unredacted —
+ * with a one-time process warning naming the field, never its value.
+ * `test/otel-host.test.ts` asserts the writes take effect on a real span,
+ * at both ends of the declared SDK range.
+ *
+ * This file never imports `@opentelemetry/sdk-trace-base` at runtime — the
+ * imports below are `import type`, erased at compile time. A
+ * `SpanProcessor` is a structural (duck-typed) interface in JS, so
+ * wrapping one needs no dependency, and this module is testable with a
+ * plain object.
+ */
+import type { ReadableSpan, Span, SpanProcessor } from "@opentelemetry/sdk-trace-base";
+import type { MaskLeafOptions, ScanAndRedact, ValueCounts } from "@redact-secret/adapter";
+/**
+ * @deprecated Use `MaskLeafOptions` (`{ policy, maxStringLength }`), which
+ * this package re-exports; this alias adds nothing and will be removed in a
+ * future major version.
+ */
+export type RedactAttributesOptions = MaskLeafOptions;
+/**
+ * One summary per **span**, the unit a host counts in
+ * (redact-secret/redact-secret-adapters#45). Every field is bounded and
+ * enumerated; `values`' definitions are in `@redact-secret/adapter`'s
+ * `outcome.ts`. No attribute name, key, value or error text is in it.
+ */
+export interface OtelSpanOutcome {
+    readonly host: "otel";
+    readonly unit: "span";
+    readonly values: ValueCounts;
+    /**
+     * `true` when **this processor** did not hand the span to the next one,
+     * because a masked value would not write back. It does not mean the span
+     * was sampled out, and `false` does not mean the span was exported: whether
+     * the next processor kept it and whether an exporter succeeded are things
+     * this adapter never learns and does not report.
+     */
+    readonly dropped: boolean;
+}
+export interface RedactingSpanProcessorOptions extends MaskLeafOptions {
+    /**
+     * Observational: called once per span, synchronously at the end of `onEnd`,
+     * after the span has either been forwarded or dropped. Increment your own
+     * counters from it.
+     *
+     * It cannot change what is exported, and anything it throws is swallowed,
+     * never read, and never rethrown — including for a span that was dropped.
+     * It is re-entrancy-guarded. No exporter or network client is created for it.
+     */
+    readonly onOutcome?: (outcome: OtelSpanOutcome) => void;
+}
+/**
+ * Mutates `attributes` in place. A no-op for `undefined`/`null`. Throws a
+ * `TypeError` naming no value if a masked value cannot be written back.
+ */
+export declare function redactAttributesWith(scanAndRedact: ScanAndRedact, attributes: object | null | undefined, options?: MaskLeafOptions): void;
+/**
+ * Wraps `next` (any object shaped like a `SpanProcessor`) and redacts each
+ * span's free text before delegating to it. `scanAndRedact` is injected so
+ * this class is testable without the built native addon; see `./index.ts`
+ * for the live factory.
+ */
+export declare class RedactingSpanProcessorWith implements SpanProcessor {
+    #private;
+    constructor(next: SpanProcessor, scanAndRedact: ScanAndRedact, options?: RedactingSpanProcessorOptions);
+    onStart(...args: Parameters<SpanProcessor["onStart"]>): void;
+    /**
+     * Forwards the SDK's optional, experimental `onEnding` (called while the
+     * span is still writable). Typed structurally: it is absent from the
+     * `SpanProcessor` interface at the low end of the declared SDK range.
+     */
+    onEnding(span: Span): void;
+    /** Never throws: a span that cannot be redacted is dropped, not exported. */
+    onEnd(span: ReadableSpan): void;
+    shutdown(): Promise<void>;
+    forceFlush(): Promise<void>;
+}

package/dist/span-processor.js

@@ -0,0 +1,231 @@
+/**
+ * A `SpanProcessor` (OpenTelemetry JS, pinned against
+ * `@opentelemetry/sdk-trace-base@2.11.0`:
+ * https://github.com/open-telemetry/opentelemetry-js/blob/main/packages/sdk-trace/src/SpanProcessor.ts)
+ * that redacts the span name, every string and string-array attribute —
+ * including OpenInference (`llm.input_messages`, `input.value`, ...) and
+ * GenAI semantic-convention attributes (`gen_ai.prompt`, ...) — each event's
+ * name and attributes, the status message, and each link's attributes,
+ * before handing the span to the next processor. It does not
+ * allowlist those attribute names: every string-shaped attribute value is
+ * scanned, which covers any semantic convention without hardcoding it and
+ * without a dependency on either convention's attribute list.
+ *
+ * `ReadableSpan`'s fields are typed `readonly` but are plain, writable
+ * objects at runtime, and `onEnd` writes the masked values back in place.
+ * Every write is read back. If one does not take (a frozen bag, a setter
+ * that ignores it), the span is dropped — never forwarded unredacted —
+ * with a one-time process warning naming the field, never its value.
+ * `test/otel-host.test.ts` asserts the writes take effect on a real span,
+ * at both ends of the declared SDK range.
+ *
+ * This file never imports `@opentelemetry/sdk-trace-base` at runtime — the
+ * imports below are `import type`, erased at compile time. A
+ * `SpanProcessor` is a structural (duck-typed) interface in JS, so
+ * wrapping one needs no dependency, and this module is testable with a
+ * plain object.
+ */
+import { countLeaf, createOutcomeCounter, ERROR_MARKER, maskLeafOutcomeWith, notify, toValueCounts, } from "@redact-secret/adapter";
+/** A span field that did not take a masked write. The message names the field, never its value. */
+class UnredactableFieldError extends Error {
+}
+/**
+ * `counter` is read on every call, not captured, so one masker serves every
+ * span and the processor can swap in a fresh per-span counter.
+ */
+function maskerFor(scanAndRedact, options, counter) {
+    return (text) => {
+        try {
+            const leaf = maskLeafOutcomeWith(scanAndRedact, text, options);
+            if (counter !== undefined)
+                countLeaf(counter(), leaf);
+            return leaf.text;
+        }
+        catch {
+            if (counter !== undefined)
+                counter().failed += 1;
+            return ERROR_MARKER;
+        }
+    };
+}
+/** The masked value, or `value` itself when nothing in it changed. */
+function maskAttributeValue(mask, value) {
+    if (typeof value === "string")
+        return mask(value);
+    if (Array.isArray(value)) {
+        // OpenTelemetry allows null/undefined holes in a homogeneous array, so
+        // every string element is masked and every other element kept in place.
+        const masked = value.map((item) => (typeof item === "string" ? mask(item) : item));
+        return masked.some((item, index) => item !== value[index]) ? masked : value;
+    }
+    // Numbers and booleans cannot carry a secret as free text.
+    return value;
+}
+/** Writes `value` to `target[key]` if it differs, and throws if the write does not show. */
+function writeBack(target, key, value, field) {
+    const record = target;
+    if (record[key] === value)
+        return;
+    try {
+        record[key] = value;
+    }
+    catch {
+        throw new UnredactableFieldError(`${field} did not take the masked write`);
+    }
+    if (record[key] !== value)
+        throw new UnredactableFieldError(`${field} did not take the masked write`);
+}
+function redactBag(mask, bag, field) {
+    if (bag == null)
+        return;
+    for (const key of Object.keys(bag)) {
+        writeBack(bag, key, maskAttributeValue(mask, bag[key]), field);
+    }
+}
+/**
+ * Mutates `attributes` in place. A no-op for `undefined`/`null`. Throws a
+ * `TypeError` naming no value if a masked value cannot be written back.
+ */
+export function redactAttributesWith(scanAndRedact, attributes, options = {}) {
+    try {
+        redactBag(maskerFor(scanAndRedact, options), attributes, "attributes");
+    }
+    catch {
+        throw new TypeError("redactAttributesWith: a masked attribute could not be written back");
+    }
+}
+function redactSpan(mask, span) {
+    if (typeof span.name === "string")
+        writeBack(span, "name", mask(span.name), "span.name");
+    redactBag(mask, span.attributes, "span.attributes");
+    const status = span.status;
+    if (typeof status?.message === "string") {
+        const message = mask(status.message);
+        // Replaced, not mutated: the status object may be the caller's own.
+        if (message !== status.message)
+            writeBack(span, "status", { ...status, message }, "span.status");
+    }
+    for (const [index, event] of (span.events ?? []).entries()) {
+        if (typeof event.name === "string")
+            writeBack(event, "name", mask(event.name), `span.events[${index}].name`);
+        redactBag(mask, event.attributes, `span.events[${index}].attributes`);
+    }
+    for (const [index, link] of (span.links ?? []).entries()) {
+        redactBag(mask, link.attributes, `span.links[${index}].attributes`);
+    }
+}
+/**
+ * Wraps `next` (any object shaped like a `SpanProcessor`) and redacts each
+ * span's free text before delegating to it. `scanAndRedact` is injected so
+ * this class is testable without the built native addon; see `./index.ts`
+ * for the live factory.
+ */
+export class RedactingSpanProcessorWith {
+    #next;
+    #mask;
+    #onOutcome;
+    #counter = createOutcomeCounter();
+    #reporting = false;
+    #warned = false;
+    constructor(next, scanAndRedact, options = {}) {
+        if (typeof next?.onEnd !== "function") {
+            throw new TypeError("RedactingSpanProcessorWith: next must be a SpanProcessor");
+        }
+        if (typeof scanAndRedact !== "function") {
+            throw new TypeError("RedactingSpanProcessorWith: scanAndRedact must be a function");
+        }
+        const { onOutcome, ...maskOptions } = options;
+        if (onOutcome !== undefined && typeof onOutcome !== "function") {
+            throw new TypeError("RedactingSpanProcessorWith: onOutcome must be a function");
+        }
+        this.#next = next;
+        this.#onOutcome = onOutcome;
+        this.#mask = maskerFor(scanAndRedact, maskOptions, onOutcome === undefined ? undefined : () => this.#counter);
+    }
+    onStart(...args) {
+        this.#next.onStart?.(...args);
+    }
+    /**
+     * Forwards the SDK's optional, experimental `onEnding` (called while the
+     * span is still writable). Typed structurally: it is absent from the
+     * `SpanProcessor` interface at the low end of the declared SDK range.
+     */
+    onEnding(span) {
+        this.#next.onEnding?.(span);
+    }
+    /** Never throws: a span that cannot be redacted is dropped, not exported. */
+    onEnd(span) {
+        const counting = this.#onOutcome !== undefined;
+        // A fresh counter per span, so `onOutcome` reports this span's values and
+        // not a running total, and the previous one is restored: a downstream
+        // processor may end a span synchronously inside `#next.onEnd` below (a
+        // `SimpleSpanProcessor` over an instrumented exporter, or any processor
+        // that emits a span of its own), which re-enters this method.
+        const outer = this.#counter;
+        if (counting)
+            this.#counter = createOutcomeCounter();
+        let dropped = false;
+        let counts;
+        try {
+            try {
+                redactSpan(this.#mask, span);
+            }
+            catch (error) {
+                this.#warnDropped(error instanceof UnredactableFieldError ? error.message : "unexpected span shape");
+                dropped = true;
+            }
+            // Snapshotted before delegating, because this span's numbers are final
+            // here and `#report` runs after a nested `onEnd` may have replaced the
+            // field.
+            if (counting)
+                counts = toValueCounts(this.#counter);
+        }
+        finally {
+            this.#counter = outer;
+        }
+        // Reported whether the span was forwarded or dropped, and after the next
+        // processor has had it, so an observer cannot affect what is exported.
+        try {
+            if (!dropped)
+                this.#next.onEnd(span);
+        }
+        finally {
+            if (counts !== undefined)
+                this.#report(counts, dropped);
+        }
+    }
+    #report(values, dropped) {
+        if (this.#onOutcome === undefined || this.#reporting)
+            return;
+        this.#reporting = true;
+        try {
+            notify(this.#onOutcome, { host: "otel", unit: "span", values, dropped });
+        }
+        finally {
+            this.#reporting = false;
+        }
+    }
+    shutdown() {
+        return this.#next.shutdown();
+    }
+    forceFlush() {
+        return this.#next.forceFlush ? this.#next.forceFlush() : Promise.resolve();
+    }
+    #warnDropped(reason) {
+        if (this.#warned)
+            return;
+        this.#warned = true;
+        const message = `@redact-secret/adapter-otel: dropped a span that could not be redacted (${reason})`;
+        try {
+            if (typeof process !== "undefined" && typeof process.emitWarning === "function") {
+                process.emitWarning(message, { code: "REDACT_SECRET_SPAN_DROPPED" });
+            }
+            else {
+                console.warn(message);
+            }
+        }
+        catch {
+            // A warning is best effort; the span is dropped either way.
+        }
+    }
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@redact-secret/adapter-otel-trace",
+  "version": "0.1.0",
+  "description": "A redacting OpenTelemetry JS SpanProcessor (traces only) over the Redact Secret core.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "CHANGELOG.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": "20.x || 22.x || 24.x"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/redact-secret/redact-secret-adapters.git",
+    "directory": "packages/adapter-otel-trace"
+  },
+  "homepage": "https://github.com/redact-secret/redact-secret-adapters/tree/main/packages/adapter-otel-trace#readme",
+  "bugs": {
+    "url": "https://github.com/redact-secret/redact-secret-adapters/issues"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "@redact-secret/adapter": "^0.1.3"
+  },
+  "peerDependencies": {
+    "@opentelemetry/sdk-trace-base": "^2.0.0",
+    "@redact-secret/core": "^0.1.0-beta.6"
+  },
+  "devDependencies": {
+    "@opentelemetry/sdk-trace-base": "^2.0.0",
+    "@redact-secret/core": "^0.1.0-beta.6",
+    "@opentelemetry/otlp-transformer": "^0.222.0"
+  }
+}