@ciphyrshq/sdk 2.6.0 → 3.0.0

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/no-network.test-helper.js

@@ -0,0 +1,108 @@
+// ═══════════════════════════════════════════════════════════════════════════
+//  The test suite may not open a socket. Enforced here, not by convention.
+//
+//  WHY. fail-posture.test.js built a real CiphyrsClient — whose baseUrl
+//  defaults to https://www.ciphyrs.com — and wrapped tools with protectTool,
+//  which queues a tool-inventory announce on a 2s debounce. Every `npm test`
+//  run therefore made two real POSTs to the PRODUCTION announce endpoint with
+//  a fake API key, and the last test in that file swapped global fetch and
+//  restored it, so the debounce fired on the real fetch after the restore. No
+//  amount of stubbing in the right order fixes that: the announce is timed,
+//  and the test that "protects" it has already finished.
+//
+//  So the guard sits BELOW fetch, at the socket, and is installed when this
+//  module is imported — before any test body runs. Whatever a test does to
+//  globalThis.fetch, whichever library it reaches for, and whenever a stray
+//  timer fires, the connection does not happen and the run fails.
+//
+//  Import it for side effect at the top of every test file:
+//
+//      import './no-network.test-helper.js'
+//
+//  `node --test` runs each test file in its own process, so each file needs
+//  its own import; a file without one is unguarded.
+//
+//  Not part of the published API. It lives in src/ because src/*.test.js does,
+//  and it is deliberately NOT named *.test.js so the runner does not treat it
+//  as a suite of its own.
+// ═══════════════════════════════════════════════════════════════════════════
+import net from 'node:net'
+import tls from 'node:tls'
+
+/** Every blocked attempt, in order. Emptied only by expectBlocked(). */
+const attempts = []
+
+// net.connect() normalises its arguments before calling Socket.prototype.connect,
+// so what arrives is `[[{ host, port }, cb]]` for a URL-shaped dial and
+// `(port, host)` for a direct socket.connect — both are unwrapped here so the
+// failure message names the host a test was reaching for.
+const describeTarget = (arg, second) => {
+  if (Array.isArray(arg)) return describeTarget(arg[0], arg[1])
+  if (arg && typeof arg === 'object') return `${arg.host || arg.path || '?'}:${arg.port ?? '?'}`
+  if (typeof arg === 'number') return `${typeof second === 'string' ? second : 'localhost'}:${arg}`
+  return String(arg)
+}
+
+function refuse(via, ...args) {
+  const target = describeTarget(args.length > 1 ? args : args[0])
+  const message =
+    `[no-network] a test tried to open a socket to ${target} (${via}). ` +
+    'Tests must never reach the network: stub the client method, or point the client at a fake. ' +
+    'If a real CiphyrsClient is needed, give it a sentinel baseUrl and neutralise _announceTools.'
+  attempts.push(message)
+  // Throwing is not enough on its own. The tool-inventory announce is
+  // best-effort and swallows its own errors (`.catch(() => {})`), and a timer
+  // that fires between tests belongs to no test, so an exception there would
+  // be invisible. The process exit code is what the suite cannot swallow —
+  // see the exit handler below.
+  throw new Error(message)
+}
+
+net.Socket.prototype.connect = function blockedConnect(...args) {
+  refuse('net.Socket.connect', ...args)
+}
+
+// TLSSocket inherits the patched connect above, so this is belt and braces for
+// the paths that hand tls.connect an already-open socket.
+tls.connect = function blockedTlsConnect(...args) {
+  refuse('tls.connect', ...args)
+}
+
+process.on('exit', () => {
+  if (!attempts.length) return
+  console.error(`\n[no-network] ${attempts.length} network attempt(s) were blocked during this test file:`)
+  for (const a of attempts) console.error(`  - ${a}`)
+  // A test that opened a socket may still have "passed" — the announce that
+  // started this swallowed its own failure. Failing the process is what makes
+  // the run red: node --test reports a non-zero subprocess as a failed file.
+  process.exitCode = 1
+})
+
+/**
+ * The attempts blocked so far. For assertions; do not mutate.
+ */
+export function networkAttempts() {
+  return [...attempts]
+}
+
+/**
+ * Run `fn`, assert it was stopped by this guard, and un-record the attempt so
+ * the deliberate one does not fail the run. This is how the guard proves it
+ * still works — a guard nothing exercises is a guard that quietly stops
+ * guarding.
+ *
+ * @returns {string} the message the guard produced
+ */
+export function expectBlocked(fn) {
+  const before = attempts.length
+  let err
+  try { fn() } catch (e) { err = e }
+  const recorded = attempts.splice(before)
+  if (!recorded.length) {
+    throw new Error('[no-network] expected the guard to block this call, but it went through')
+  }
+  if (!err || !/no-network/.test(err.message)) {
+    throw new Error(`[no-network] the guard recorded the attempt but did not throw for it (got: ${err?.message})`)
+  }
+  return recorded[0]
+}

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;