@ciphyrshq/sdk 2.6.0 → 3.0.1

package/src/context.js

@@ -0,0 +1,82 @@
+// ═══════════════════════════════════════════════════════════════════════════
+//  Ambient trace/span context for the JavaScript SDK.
+//
+//  WHY. Spans took `parentSpanId` as a hand-threaded option, so in practice
+//  nothing was ever nested: every span in a trace arrived parentless. The
+//  server derives the topology graph from parent links, so a flat trace draws
+//  no edges — the customer saw a row of disconnected agents and concluded
+//  topology was broken. It also meant a guard call inside a span had no span
+//  to point at, exactly the defect the Python SDK had (measured on
+//  production: every guard-path detection had a NULL span_id).
+//
+//  AsyncLocalStorage, not a module global: a global is wrong the moment two
+//  requests are in flight, which is the normal shape of a Node agent. ALS is
+//  per-async-context and is inherited by anything the current task spawns.
+//
+//  TWO WAYS IN, deliberately. `span.run(fn)` is a real scope and is what the
+//  docs recommend. But this SDK's public shape has always been
+//  `const s = trace.span(...); …; s.end()`, with no callback, so
+//  `enterWith` is used at construction and unwound at `end()`. That is what
+//  makes the existing style nest correctly without asking every user to
+//  rewrite their agent.
+// ═══════════════════════════════════════════════════════════════════════════
+import { AsyncLocalStorage } from 'node:async_hooks';
+
+export const traceStorage = new AsyncLocalStorage();
+export const spanStorage = new AsyncLocalStorage();
+
+/** The trace/span an inbound request arrived under (see propagation.js). */
+export const remoteStorage = new AsyncLocalStorage();
+
+/**
+ * The active trace and span, if any.
+ *
+ * Prefers the span, which carries both ids — a guard call made inside span()
+ * should attribute to that span, not merely to its trace. Falls back to the
+ * remote parent so a guard call made straight from a request handler, with no
+ * local span open, still attributes to the distributed trace it belongs to.
+ * Returns an object with undefined fields rather than null so callers can
+ * spread it without branching.
+ */
+export function activeIds() {
+  const span = spanStorage.getStore();
+  if (span?.trace_id) {
+    return { trace_id: span.trace_id, span_id: span.span_id };
+  }
+  const trace = traceStorage.getStore();
+  if (trace?.trace_id) {
+    return { trace_id: trace.trace_id, span_id: undefined };
+  }
+  const remote = remoteStorage.getStore();
+  if (remote?.trace_id) {
+    return { trace_id: remote.trace_id, span_id: remote.span_id };
+  }
+  return { trace_id: undefined, span_id: undefined };
+}
+
+/**
+ * The kind of the innermost LOCAL span ('agent' | 'tool' | 'llm' | 'retriever'),
+ * or undefined when no local span is open.
+ *
+ * Only spanStorage answers this, deliberately. A span kind never travels in
+ * Ciphyrs baggage, so a remote parent has none, and a trace is not a span —
+ * in both of those cases the honest answer is "I do not know what that span
+ * is", not "agent". The one caller that needs it is protect-tool.js: telling
+ * the gateway which span authorised a tool call is only true if the span is
+ * the tool span, and claiming it otherwise is worse than saying nothing.
+ */
+export function activeSpanKind() {
+  return spanStorage.getStore()?.kind || undefined;
+}
+
+/** The agent name of the innermost active span, for outbound headers. */
+export function activeAgent() {
+  return spanStorage.getStore()?.agent_name
+    || remoteStorage.getStore()?.agent_name
+    || undefined;
+}
+
+/** The remote parent, if this async context is serving an instrumented request. */
+export function remoteParent() {
+  return remoteStorage.getStore() || undefined;
+}

package/src/fail-posture.js

@@ -0,0 +1,100 @@
+// ═══════════════════════════════════════════════════════════════════════════
+//  One failure posture for the whole client.
+//
+//  WHY. The three entry points that stand between a customer and their
+//  LLM/tool disagreed about what a Ciphyrs outage means. protectTool caught
+//  the transport error and ran the tool anyway (fail-OPEN); guard.wrap and
+//  scan.protect let the error propagate out of check()/mask(), so nothing ran
+//  (fail-CLOSED). One client, two opposite behaviours under one outage — and
+//  the unsafe one sat on the path that authorises tool execution, i.e. the
+//  path that moves money. Neither closed path offered any way to opt out, so
+//  a customer could not align them either.
+//
+//  So the posture is one option, resolved here, and used identically by all
+//  three: `failOpen: true` means "a Ciphyrs outage must not stop my work",
+//  `failOpen: false` (the default, everywhere) means the work does not
+//  proceed. Settable on the client and overridable per call.
+// ═══════════════════════════════════════════════════════════════════════════
+
+/** What to tell a caller who just got blocked by an outage. */
+export const FAIL_OPEN_HINT =
+  'To run anyway while Ciphyrs is unreachable, pass { failOpen: true } on this call ' +
+  'or construct the client with new CiphyrsClient({ failOpen: true }).'
+
+/**
+ * Read one posture value: true, false, or undefined for "nobody chose".
+ *
+ * WHY this is not `Boolean(v)` / `!v`. A posture reaches us from
+ * configuration at least as often as from code — a JSON file, an env var, a
+ * database column, a `{ ...defaults }` spread — and those hand over `null` or
+ * a string, which plain truthiness reads the UNSAFE way:
+ *
+ *   `!null` is true, so a `failClosed` column nobody has ever set resolved to
+ *   fail OPEN — an unset value silently choosing the direction that runs the
+ *   tool during an outage.
+ *   `Boolean('false')` is true, so `failOpen: process.env.FAIL_OPEN` with the
+ *   var set to "false" resolved to fail OPEN too — a written-down "no" read as
+ *   a yes.
+ *
+ * Fail-open is the direction that costs the customer money or leaks their PII,
+ * so it is only ever reached by a value that unmistakably says so. Anything
+ * else — null, '', an object, NaN, a string we cannot read — is "no choice
+ * made", which falls through to the next level and ultimately to fail CLOSED.
+ * Note the asymmetry that made this urgent: a nullish `failOpen` already
+ * landed safely; only the inverted key landed unsafely.
+ */
+const YES = new Set(['true', '1', 'yes', 'on'])
+const NO = new Set(['false', '0', 'no', 'off'])
+
+function readPosture(v) {
+  if (v === undefined || v === null) return undefined
+  if (typeof v === 'boolean') return v
+  // 0/1 is how a boolean survives MySQL and SQLite, so a number is a real
+  // choice — except NaN, which is what `Number(undefined)` produces.
+  if (typeof v === 'number') return Number.isFinite(v) ? v !== 0 : undefined
+  if (typeof v === 'string') {
+    const s = v.trim().toLowerCase()
+    if (YES.has(s)) return true
+    if (NO.has(s)) return false
+    return undefined   // '' or anything unrecognised: not a choice
+  }
+  return undefined     // objects, arrays, functions: not a posture
+}
+
+/**
+ * Should this call proceed when Ciphyrs cannot be reached?
+ *
+ * @param {object} [callOpts]      Per-call options ({ failOpen }, plus legacy
+ *                                 { failClosed } on the surfaces that opt in)
+ * @param {boolean} [clientDefault=false]  The client-wide posture
+ * @param {object} [surface]
+ * @param {boolean} [surface.legacyFailClosed=false]
+ *        Read the legacy `failClosed` key on this surface. OFF by default, and
+ *        opted into by protectTool alone, because protectTool is the only
+ *        surface `failClosed` ever did anything on. guard.wrap ignored the key
+ *        outright and scan.protect forwarded it to mask(), which whitelists its
+ *        fields, so it was inert there too. Reading it everywhere turned a key
+ *        someone copy-pasted from a protectTool call site into a live switch on
+ *        two new surfaces — and `{ failClosed: false }` on scan.protect means
+ *        sending UNMASKED text to the customer's model. A resolver shared by
+ *        three surfaces must not hand a fourth one the legacy key by default.
+ * @returns {boolean} true = fail open (run anyway), false = fail closed (do not run)
+ */
+export function resolveFailOpen(callOpts, clientDefault = false, { legacyFailClosed = false } = {}) {
+  const o = (callOpts && typeof callOpts === 'object') ? callOpts : {}
+
+  const open = readPosture(o.failOpen)
+  if (open !== undefined) return open
+
+  // `failClosed` has shipped on protectTool since V60 and must keep working in
+  // BOTH directions there. A caller who wrote `failClosed: false` wrote down a
+  // request to fail open; silently re-reading that as "did not choose" and
+  // applying the new fail-closed default is precisely the upgrade surprise
+  // this option exists to prevent.
+  if (legacyFailClosed) {
+    const closed = readPosture(o.failClosed)
+    if (closed !== undefined) return !closed
+  }
+
+  return readPosture(clientDefault) === true
+}

package/src/index.js

@@ -9,5 +9,19 @@ export {
   CiphyrsJobTimeoutError,
 } from './errors.js';
 export { CiphyrsTracer, Trace, Span } from './tracer.js';
+// 2.7 — cross-process trace propagation: what makes agents in separate
+// processes appear as one connected topology instead of isolated nodes.
+export {
+  inject, extract, withRemoteContext, currentContext,
+  instrumentFetch, instrumentHttp, autoInstrument,
+  expressMiddleware, fastifyPlugin, withPropagation,
+  w3cTraceId, w3cSpanId, TRACEPARENT, BAGGAGE,
+} from './propagation.js';
+// activeSpanKind is exported alongside the ids because "which span am I in?"
+// is not answerable from the ids alone, and the answer decides whether a span
+// id may be reported to the tool gate at all — see protect-tool.js.
+export { activeIds, activeAgent, activeSpanKind, remoteParent } from './context.js';
 export { SecretDetector } from './secret-detector.js';
 export { EvalRunner } from './eval-runner.js';
+// V60 — agentic governance: tool-call authorization
+export { protectTool, ToolBlocked, ToolApprovalTimeout } from './protect-tool.js';

package/src/propagation.js

@@ -0,0 +1,388 @@
+// ═══════════════════════════════════════════════════════════════════════════
+//  Trace-context propagation between agents (W3C `traceparent` + `baggage`)
+//
+//  WHY THIS EXISTS. The topology graph is derived on the server: an edge
+//  A → B is drawn when a span of agent B names a span of agent A as its
+//  parent. Inside one process the SDK's AsyncLocalStorage provides that.
+//  Across processes nothing did — the SDK never wrote `traceparent` on an
+//  outbound call and never read it on an inbound one — so two agents that
+//  talked to each other constantly rendered as two disconnected nodes.
+//
+//  Outbound: `instrumentFetch()` wraps global fetch and `instrumentHttp()`
+//  wraps node:http / node:https request+get, which together cover fetch,
+//  axios, node-fetch, got and superagent. Calls to the Ciphyrs API itself are
+//  never decorated (registerInternalOrigin, called by CiphyrsClient).
+//
+//  Inbound: `expressMiddleware()`, `fastifyPlugin()` and the generic
+//  `withRemoteContext(headers, fn)` activate the caller's trace for the
+//  duration of a request. `tracer.trace()` then continues that trace and its
+//  first span is parented to the caller's span, so the edge exists as soon as
+//  both spans arrive, in either order (server-side V143).
+//
+//  Anything else (queues, gRPC, a framework not listed): `inject(headers)`
+//  when you send, `withRemoteContext(headers, fn)` when you receive.
+//
+//  ID SHAPE. `traceparent` requires 32-hex trace ids and 16-hex span ids.
+//  Since 2.7 the tracer generates ids in exactly that shape, so the header
+//  carries the REAL ids and an OpenTelemetry-instrumented peer joins the same
+//  trace. Ids that are not hex (one you supplied, or one from an older SDK)
+//  are hashed into the W3C fields while the exact originals travel in
+//  `baggage`, so a Ciphyrs peer still links precisely.
+// ═══════════════════════════════════════════════════════════════════════════
+import { createHash } from 'node:crypto';
+import { createRequire } from 'node:module';
+import { activeAgent, remoteParent, remoteStorage, spanStorage, traceStorage } from './context.js';
+
+export const TRACEPARENT = 'traceparent';
+export const BAGGAGE = 'baggage';
+
+const B_TRACE = 'ciphyrs.trace_id';
+const B_SPAN = 'ciphyrs.span_id';
+const B_AGENT = 'ciphyrs.agent';
+const B_PROJECT = 'ciphyrs.project';
+
+const HEX32 = /^[0-9a-f]{32}$/;
+const HEX16 = /^[0-9a-f]{16}$/;
+const TRACEPARENT_RE = /^([0-9a-f]{2})-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$/;
+
+const ZERO32 = '0'.repeat(32);
+const ZERO16 = '0'.repeat(16);
+
+let defaultProject;
+/** Set by CiphyrsTracer so baggage names the caller's project. */
+export function setDefaultProject(name) { defaultProject = name || undefined; }
+
+// Origins that belong to Ciphyrs itself. Calls there are the SDK reporting
+// telemetry, not the agent doing work, and must not carry trace headers.
+const internalOrigins = new Set(['https://www.ciphyrs.com', 'https://ciphyrs.com']);
+export function registerInternalOrigin(url) {
+  try { internalOrigins.add(new URL(url).origin); } catch { /* not a URL — ignore */ }
+}
+function isInternal(url) {
+  try { return internalOrigins.has(new URL(url).origin); } catch { return false; }
+}
+
+// ── W3C field shaping ──────────────────────────────────────────────────────
+export function w3cTraceId(traceId) {
+  const t = String(traceId).toLowerCase();
+  if (HEX32.test(t)) return t;
+  return createHash('sha256').update(String(traceId)).digest('hex').slice(0, 32);
+}
+export function w3cSpanId(spanId) {
+  const s = String(spanId).toLowerCase();
+  if (HEX16.test(s)) return s;
+  return createHash('sha256').update(String(spanId)).digest('hex').slice(0, 16);
+}
+
+// ── Outbound ───────────────────────────────────────────────────────────────
+
+/**
+ * The context an outbound call should carry: the local span if we are in one,
+ * else the trace, else the remote parent we are serving (pass-through).
+ */
+export function currentContext() {
+  const span = spanStorage.getStore();
+  if (span?.trace_id) {
+    return { trace_id: span.trace_id, span_id: span.span_id, agent_name: span.agent_name, project: defaultProject };
+  }
+  const trace = traceStorage.getStore();
+  if (trace?.trace_id) {
+    return { trace_id: trace.trace_id, span_id: undefined, agent_name: activeAgent(), project: defaultProject };
+  }
+  const remote = remoteParent();
+  if (remote?.trace_id) {
+    return {
+      trace_id: remote.trace_id, span_id: remote.span_id,
+      agent_name: activeAgent() || remote.agent_name,
+      project: defaultProject || remote.project,
+    };
+  }
+  return undefined;
+}
+
+function mergeBaggage(existing, items) {
+  const kept = [];
+  for (const member of String(existing || '').split(',')) {
+    const m = member.trim();
+    if (!m) continue;
+    const key = m.split('=', 1)[0].trim();
+    if (key in items) continue;      // ours — replaced, never duplicated
+    kept.push(m);
+  }
+  for (const [k, v] of Object.entries(items)) kept.push(`${k}=${encodeURIComponent(v)}`);
+  return kept.join(',');
+}
+
+function headerValues(ctx, existingBaggage) {
+  const spanHex = ctx.span_id ? w3cSpanId(ctx.span_id) : `${'0'.repeat(15)}1`;
+  const items = { [B_TRACE]: ctx.trace_id };
+  if (ctx.span_id) items[B_SPAN] = ctx.span_id;
+  if (ctx.agent_name) items[B_AGENT] = ctx.agent_name;
+  if (ctx.project) items[B_PROJECT] = ctx.project;
+  return {
+    [TRACEPARENT]: `00-${w3cTraceId(ctx.trace_id)}-${spanHex}-01`,
+    [BAGGAGE]: mergeBaggage(existingBaggage, items),
+  };
+}
+
+/**
+ * Add `traceparent` and `baggage` for the active context.
+ *
+ * Accepts (and returns) a plain object or a Headers/fetch-style object with
+ * get/set. Outside a trace it is a no-op, so it is safe to call always:
+ *
+ *   await fetch(url, { headers: inject({ 'content-type': 'application/json' }) })
+ */
+export function inject(headers = {}) {
+  const ctx = currentContext();
+  if (!ctx) return headers;
+  const settable = typeof headers?.set === 'function';
+  const existing = settable
+    ? headers.get?.(BAGGAGE)
+    : headers[BAGGAGE] ?? headers[BAGGAGE.toUpperCase()] ?? headers.Baggage;
+  const values = headerValues(ctx, existing);
+  for (const [k, v] of Object.entries(values)) {
+    if (settable) headers.set(k, v); else headers[k] = v;
+  }
+  return headers;
+}
+
+// ── Inbound ────────────────────────────────────────────────────────────────
+
+function lookup(headers) {
+  const out = {};
+  if (!headers) return out;
+  const want = new Set([TRACEPARENT, BAGGAGE]);
+  const take = (k, v) => {
+    if (v == null) return;
+    let key = String(k).toLowerCase();
+    if (key.startsWith('http_')) key = key.slice(5).replace(/_/g, '-');   // CGI-style
+    if (want.has(key)) out[key] = Array.isArray(v) ? v[0] : String(v);
+  };
+  if (typeof headers.get === 'function') {                                 // Headers / fetch Request
+    for (const key of want) take(key, headers.get(key));
+    return out;
+  }
+  if (typeof headers.forEach === 'function' && !Array.isArray(headers)) {  // Map-like
+    headers.forEach((v, k) => take(k, v));
+    return out;
+  }
+  if (Array.isArray(headers)) {                                            // [[k, v], …]
+    for (const pair of headers) if (Array.isArray(pair)) take(pair[0], pair[1]);
+    return out;
+  }
+  for (const [k, v] of Object.entries(headers)) take(k, v);                // node req.headers
+  return out;
+}
+
+function parseBaggage(raw) {
+  const out = {};
+  for (const member of String(raw || '').split(',')) {
+    const m = member.trim();
+    if (!m || !m.includes('=')) continue;
+    const kv = m.split(';', 1)[0];
+    const idx = kv.indexOf('=');
+    const k = kv.slice(0, idx).trim();
+    if (k) out[k] = decodeURIComponent(kv.slice(idx + 1).trim());
+  }
+  return out;
+}
+
+/**
+ * Read the caller's trace context from inbound headers. Returns undefined
+ * when nothing usable is present. Ciphyrs baggage (exact ids) wins over
+ * `traceparent` (hashed/hex ids).
+ */
+export function extract(headers) {
+  const h = lookup(headers);
+  if (!Object.keys(h).length) return undefined;
+  const bag = parseBaggage(h[BAGGAGE]);
+  let traceId = bag[B_TRACE] || undefined;
+  let spanId = bag[B_SPAN] || undefined;
+  let sampled = true;
+  const tp = h[TRACEPARENT];
+  if (tp) {
+    const m = TRACEPARENT_RE.exec(String(tp).trim().toLowerCase());
+    if (m) {
+      const [, , tpTrace, tpSpan, flags] = m;
+      if (tpTrace !== ZERO32) {
+        traceId = traceId || tpTrace;
+        spanId = spanId || (tpSpan !== ZERO16 ? tpSpan : undefined);
+      }
+      const f = parseInt(flags, 16);
+      sampled = Number.isNaN(f) ? true : Boolean(f & 0x01);
+    }
+  }
+  if (!traceId) return undefined;
+  return {
+    trace_id: traceId,
+    span_id: spanId,
+    agent_name: bag[B_AGENT] || undefined,
+    project: bag[B_PROJECT] || undefined,
+    sampled,
+  };
+}
+
+/**
+ * Run `fn` as the continuation of a caller's trace:
+ *
+ *   await withRemoteContext(message.headers, async () => {
+ *     const t = tracer.trace('handle job');            // continues the trace
+ *     await t.span('worker-agent').run(async () => {}) // parented to the caller
+ *   })
+ *
+ * Accepts headers in any shape `extract` takes, or a ready context object.
+ * With nothing usable it simply runs `fn`.
+ */
+export function withRemoteContext(headersOrCtx, fn) {
+  const ctx = headersOrCtx && headersOrCtx.trace_id ? headersOrCtx : extract(headersOrCtx);
+  if (!ctx) return fn();
+  return remoteStorage.run(ctx, fn);
+}
+
+// ── Client instrumentation ─────────────────────────────────────────────────
+
+let fetchPatched = false;
+/** Wrap global fetch so calls made inside a span carry the headers. Idempotent. */
+export function instrumentFetch() {
+  if (fetchPatched || typeof globalThis.fetch !== 'function') return false;
+  const original = globalThis.fetch;
+  globalThis.fetch = function ciphyrsFetch(input, init = {}) {
+    try {
+      const url = typeof input === 'string' ? input : (input?.url ?? String(input));
+      if (!init?.ciphyrsInternal && !isInternal(url) && currentContext()) {
+        // A Request object's headers are immutable through init, so rebuild.
+        if (typeof Request !== 'undefined' && input instanceof Request) {
+          const headers = new Headers(input.headers);
+          inject(headers);
+          return original.call(this, new Request(input, { headers }), init);
+        }
+        const headers = init.headers instanceof Headers ? init.headers : new Headers(init.headers || {});
+        inject(headers);
+        return original.call(this, input, { ...init, headers });
+      }
+    } catch { /* never break the customer's call */ }
+    return original.call(this, input, init);
+  };
+  globalThis.fetch.__ciphyrsOriginal = original;
+  fetchPatched = true;
+  return true;
+}
+
+let httpPatched = false;
+/**
+ * Wrap node:http / node:https request+get, which is how axios, node-fetch,
+ * got and superagent actually send. Idempotent; returns false if already done.
+ */
+export function instrumentHttp() {
+  if (httpPatched) return false;
+  let http, https;
+  try {
+    // A static `import` of node:http would be evaluated in every environment
+    // that loads this module, including browsers/bundlers where it does not
+    // exist. createRequire keeps the dependency lazy and Node-only.
+    const req = createRequire(import.meta.url);
+    http = req('node:http');
+    https = req('node:https');
+  } catch {
+    return false;                       // not Node, or no CJS resolver
+  }
+  const patch = (mod, name, scheme) => {
+    const original = mod[name];
+    if (typeof original !== 'function' || original.__ciphyrs) return;
+    const wrapped = function ciphyrsRequest(...args) {
+      try {
+        const ctx = currentContext();
+        if (ctx) {
+          // Signatures: (url[, options][, cb]) and (options[, cb]).
+          let urlStr = null;
+          let optIdx = -1;
+          if (typeof args[0] === 'string' || args[0] instanceof URL) {
+            urlStr = String(args[0]);
+            if (args[1] && typeof args[1] === 'object') optIdx = 1;
+          } else if (args[0] && typeof args[0] === 'object') {
+            optIdx = 0;
+            const o = args[0];
+            const host = o.host || o.hostname || 'localhost';
+            urlStr = `${o.protocol || scheme}//${host}${o.path || '/'}`;
+          }
+          if (!isInternal(urlStr)) {
+            if (optIdx === -1) {
+              // No options object to carry headers — add one.
+              const opts = {};
+              inject(opts.headers = {});
+              args.splice(typeof args[1] === 'function' ? 1 : args.length, 0, opts);
+            } else {
+              const opts = args[optIdx];
+              opts.headers = opts.headers || {};
+              inject(opts.headers);
+            }
+          }
+        }
+      } catch { /* never break the customer's call */ }
+      return original.apply(this, args);
+    };
+    wrapped.__ciphyrs = true;
+    wrapped.__ciphyrsOriginal = original;
+    mod[name] = wrapped;
+  };
+  patch(http, 'request', 'http:');
+  patch(http, 'get', 'http:');
+  patch(https, 'request', 'https:');
+  patch(https, 'get', 'https:');
+  httpPatched = true;
+  return true;
+}
+
+/** Instrument every supported outbound client. Called by CiphyrsTracer. */
+export function autoInstrument() {
+  return { fetch: instrumentFetch(), http: instrumentHttp() };
+}
+
+// ── Server integrations ────────────────────────────────────────────────────
+
+/**
+ * Express / Connect middleware:
+ *
+ *   app.use(expressMiddleware())
+ */
+export function expressMiddleware() {
+  return function ciphyrsPropagation(req, res, next) {
+    const ctx = extract(req.headers);
+    if (!ctx) return next();
+    return remoteStorage.run(ctx, () => next());
+  };
+}
+
+/**
+ * Fastify plugin:
+ *
+ *   await app.register(fastifyPlugin)
+ *
+ * Uses an onRequest hook wrapped around the rest of the lifecycle via
+ * AsyncLocalStorage.run, which Fastify propagates to handlers.
+ */
+export async function fastifyPlugin(app) {
+  app.addHook('onRequest', (req, reply, done) => {
+    const ctx = extract(req.headers);
+    if (!ctx) return done();
+    return remoteStorage.run(ctx, () => done());
+  });
+}
+fastifyPlugin[Symbol.for('skip-override')] = true;
+
+/**
+ * Raw node http handler wrapper:
+ *
+ *   http.createServer(withPropagation((req, res) => { … }))
+ */
+export function withPropagation(handler) {
+  return function ciphyrsHandler(req, res) {
+    const ctx = extract(req.headers);
+    if (!ctx) return handler(req, res);
+    return remoteStorage.run(ctx, () => handler(req, res));
+  };
+}
+
+/** @internal — exported for tests. */
+export const _parseBaggage = parseBaggage;