@ciphyrshq/sdk 2.6.0 → 3.0.0

package/src/client.test.js

@@ -0,0 +1,99 @@
+/**
+ * Retry behaviour of the SDK's HTTP helper — parity with the Python client.
+ * Run with: node --test src/client.test.js
+ *
+ *  · A guard verdict (/v1/guard/*) is bounded: one retry, a short attempt
+ *    timeout, a 10 s wall-clock budget. The BFSI demo hung for 90 s on a
+ *    transfer request while the Python SDK retried tool-check on the
+ *    general ladder; this client had the same ladder.
+ *  · A 5xx whose body carries fail_open / fail_closed IS the verdict and is
+ *    returned, not retried (Python SDK, 13 Sep 2026).
+ *  · Retry-After is honoured but capped at 60 s.
+ *  · Everything else keeps the ladder it had.
+ */
+import { test, describe, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { _retryInternals as R } from './client.js';
+
+let realFetch;
+beforeEach(() => { realFetch = globalThis.fetch; });
+afterEach(() => { globalThis.fetch = realFetch; });
+
+function respond(status, body, headers = {}) {
+  const calls = { n: 0, timeouts: [] };
+  globalThis.fetch = async (url, init) => {
+    calls.n += 1;
+    calls.timeouts.push(init?.signal);
+    return new Response(JSON.stringify(body), { status, headers: { 'content-type': 'application/json', ...headers } });
+  };
+  return calls;
+}
+
+describe('guard calls are bounded', () => {
+  test('a 5xx on tool-check is retried once at most, quickly', async () => {
+    const calls = respond(503, { error: 'classifier unavailable' });
+    const t0 = Date.now();
+    await assert.rejects(R.request('https://api.test/v1/guard/tool-check', { method: 'POST', body: {} }));
+    assert.ok(calls.n <= R.GUARD_MAX_RETRIES + 1, `${calls.n} attempts`);
+    assert.ok(Date.now() - t0 < 3000, 'no long backoff on a verdict');
+  });
+  test('a 5xx on guard/check likewise', async () => {
+    const calls = respond(502, { error: 'bad gateway' });
+    await assert.rejects(R.request('https://api.test/v1/guard/check', { method: 'POST', body: {} }));
+    assert.ok(calls.n <= R.GUARD_MAX_RETRIES + 1);
+  });
+  test('ingest keeps the full ladder', async () => {
+    const calls = respond(503, { error: 'upstream unavailable' });
+    await assert.rejects(R.request('https://api.test/v1/trace/spans', { method: 'POST', body: {}, timeout: 500 }));
+    assert.equal(calls.n, R.MAX_RETRIES + 1);
+  });
+  test('isGuardUrl reads the path, not the host', () => {
+    assert.equal(R.isGuardUrl('https://www.ciphyrs.com/v1/guard/tool-check'), true);
+    assert.equal(R.isGuardUrl('https://ca.ciphyrs.com/v1/guard/check?x=1'), true);
+    assert.equal(R.isGuardUrl('https://www.ciphyrs.com/v1/trace/spans'), false);
+    assert.equal(R.isGuardUrl('https://guard.example.com/v1/scan/mask'), false);
+  });
+});
+
+describe('a final verdict is not retried', () => {
+  test('503 with fail_open is returned as the verdict, once', async () => {
+    const calls = respond(503, { action: 'allow', fail_open: true, reason: 'tool-check service error; failed open' });
+    const out = await R.request('https://api.test/v1/guard/tool-check', { method: 'POST', body: {} });
+    assert.equal(calls.n, 1);
+    assert.equal(out.fail_open, true);
+  });
+  test('503 with fail_closed likewise', async () => {
+    const calls = respond(503, { action: 'block', fail_closed: true, reason: 'failing closed' });
+    const out = await R.request('https://api.test/v1/guard/tool-check', { method: 'POST', body: {} });
+    assert.equal(calls.n, 1);
+    assert.equal(out.fail_closed, true);
+  });
+  test('carriesFinalVerdict is strict about the marker', () => {
+    assert.equal(R.carriesFinalVerdict({ fail_open: true }), true);
+    assert.equal(R.carriesFinalVerdict({ fail_open: 'yes' }), false);
+    assert.equal(R.carriesFinalVerdict({ error: 'x' }), false);
+    assert.equal(R.carriesFinalVerdict(null), false);
+  });
+});
+
+describe('Retry-After is capped', () => {
+  test('a huge Retry-After does not park the thread', async () => {
+    let n = 0;
+    globalThis.fetch = async () => {
+      n += 1;
+      return new Response(JSON.stringify({ error: 'limit' }), { status: 429, headers: { 'retry-after': n === 1 ? '3600' : '0', 'content-type': 'application/json' } });
+    };
+    const t0 = Date.now();
+    // Not a guard path: the general ladder applies, so the first sleep is
+    // the Retry-After — capped. We cannot wait 60 s in a test, so assert the
+    // cap constant and that the code path used it by racing a short timer.
+    const race = Promise.race([
+      R.request('https://api.test/v1/trace/spans', { method: 'POST', body: {}, timeout: 500 }).catch(() => 'done'),
+      new Promise((r) => setTimeout(() => r('still sleeping'), 1500)),
+    ]);
+    const outcome = await race;
+    assert.equal(outcome, 'still sleeping', 'the capped Retry-After (60 s) is still honoured, so the request is asleep');
+    assert.equal(R.MAX_RETRY_AFTER_MS, 60_000);
+    assert.ok(Date.now() - t0 < 2500);
+  });
+});

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/fail-posture.test.js

@@ -0,0 +1,385 @@
+/**
+ * One failure posture, three entry points.
+ *
+ * The audit this fixes: protectTool caught a gateway outage and ran the tool
+ * anyway, while guard.wrap and scan.protect on the SAME client let the error
+ * out and refused to proceed. One client, two opposite answers to "Ciphyrs is
+ * down", with the unsafe one on the path that authorises tool execution — and
+ * no option anywhere to align them.
+ *
+ * So the question these tests ask is not "does it block?" but: DO ALL THREE
+ * ANSWER THE OUTAGE THE SAME WAY, and does the caller's choice reach all three
+ * from both the client and the call?
+ *
+ * protectTool's own outage tests live in protect-tool.test.js; this file
+ * covers guard.wrap, scan.protect, and the resolution rule they share.
+ */
+
+import './no-network.test-helper.js'
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+import net from 'node:net'
+import { CiphyrsClient } from './client.js'
+import { CiphyrsError } from './errors.js'
+import { resolveFailOpen } from './fail-posture.js'
+import { expectBlocked, networkAttempts } from './no-network.test-helper.js'
+
+// These tests need a REAL client — the posture is resolved in its constructor
+// and read by three of its methods — and a real client is a loaded gun in a
+// test file. Two things are disarmed here, at construction, so no test can
+// re-arm them by running in the wrong order:
+//
+//   baseUrl        — it defaults to https://www.ciphyrs.com. Every request
+//                    this file provokes used to be aimed at production.
+//   _announceTools — protectTool announces every wrapped tool on a 2s
+//                    debounce, and queueToolAnnounce skips the registry
+//                    entirely when the client has no _announceTools function.
+//                    Shadowing the prototype method with `undefined` means the
+//                    timer is never even created, so there is nothing left to
+//                    fire after the last test has restored whatever it stubbed.
+//
+// The socket guard imported above is the backstop for both.
+const SENTINEL_BASE = 'http://ciphyrs.invalid'
+const clientWith = (opts = {}) => {
+  const c = new CiphyrsClient({ apiKey: 'cyp_test_key', baseUrl: SENTINEL_BASE, ...opts })
+  c._announceTools = undefined
+  return c
+}
+
+// An outage is "the primitive threw after its retries were exhausted", which
+// is what request() does on a 503 or a refused connection. Stubbing the
+// primitive keeps these tests off the retry/backoff clock; the one test at the
+// bottom drives a real transport failure end to end.
+const OUTAGE = () => { throw new CiphyrsError('ECONNREFUSED') }
+const downGuard = (c) => { c.guard.check = async () => OUTAGE(); return c }
+const downMasker = (c) => { c.scan.mask = async () => OUTAGE(); return c }
+
+// ── The resolution rule itself ──────────────────────────────────────────────
+
+describe('resolveFailOpen — precedence', () => {
+  it('fails closed when nobody chose', () => {
+    assert.equal(resolveFailOpen(undefined, undefined), false)
+    assert.equal(resolveFailOpen({}, false), false)
+  })
+
+  it('takes the client posture when the call is silent', () => {
+    assert.equal(resolveFailOpen({}, true), true)
+  })
+
+  it('lets the call override the client, in both directions', () => {
+    assert.equal(resolveFailOpen({ failOpen: false }, true), false)
+    assert.equal(resolveFailOpen({ failOpen: true }, false), true)
+  })
+
+  it('reads legacy failClosed in both directions — on the surfaces that ask for it', () => {
+    // `failClosed: false` is a caller who WROTE DOWN a fail-open posture.
+    // Re-reading that as "made no choice" and applying the new default is the
+    // silent upgrade break this whole option exists to avoid. Only protectTool
+    // opts in, so only protectTool's call shape is asserted here.
+    const legacy = { legacyFailClosed: true }
+    assert.equal(resolveFailOpen({ failClosed: false }, false, legacy), true)
+    assert.equal(resolveFailOpen({ failClosed: true }, true, legacy), false)
+  })
+
+  it('ignores legacy failClosed unless the surface opts in', () => {
+    // guard.wrap and scan.protect call it WITHOUT the flag. The key was inert
+    // on both before the shared resolver existed, and honouring it there turns
+    // a copy-pasted protectTool option into a live switch — on scan.protect,
+    // one that sends unmasked text to the customer's model.
+    assert.equal(resolveFailOpen({ failClosed: false }, false), false)
+    assert.equal(resolveFailOpen({ failClosed: false }, true), true, 'it must not override the client either')
+  })
+
+  it('prefers the new spelling when a caller passes both', () => {
+    assert.equal(resolveFailOpen({ failOpen: false, failClosed: false }, true, { legacyFailClosed: true }), false)
+  })
+})
+
+describe('resolveFailOpen — values that are not a choice', () => {
+  // Postures arrive from JSON config, a database column and `{ ...defaults }`
+  // spreads, which produce null and strings. Every one of these used to be
+  // read by plain truthiness, and the inverted key read them all the UNSAFE
+  // way: `!null` is true, so an unset column meant fail OPEN.
+  const legacy = { legacyFailClosed: true }
+
+  it('treats a nullish legacy failClosed as unset, not as fail open', () => {
+    assert.equal(resolveFailOpen({ failClosed: null }, false, legacy), false)
+    assert.equal(resolveFailOpen({ failClosed: undefined }, false, legacy), false)
+  })
+
+  it('lets the client posture through when the call value is nullish', () => {
+    // Unset means "I did not choose", so the next level decides — it does not
+    // mean "fail open" and it does not mean "override the client with closed".
+    assert.equal(resolveFailOpen({ failClosed: null }, true, legacy), true)
+    assert.equal(resolveFailOpen({ failOpen: null }, true), true)
+  })
+
+  it('treats a nullish failOpen as unset too — the two keys agree', () => {
+    assert.equal(resolveFailOpen({ failOpen: null }, false), false)
+  })
+
+  it('reads a string posture as written, not as truthiness', () => {
+    // `Boolean('false')` is true. A config file or an env var that says "false"
+    // must not turn into fail OPEN.
+    assert.equal(resolveFailOpen({ failOpen: 'false' }, false), false)
+    assert.equal(resolveFailOpen({ failOpen: 'true' }, false), true)
+    assert.equal(resolveFailOpen({ failClosed: 'true' }, true, legacy), false)
+    assert.equal(resolveFailOpen({ failClosed: 'false' }, false, legacy), true)
+  })
+
+  it('refuses to guess at an empty string or a value it cannot read', () => {
+    assert.equal(resolveFailOpen({ failOpen: '' }, false), false)
+    assert.equal(resolveFailOpen({ failClosed: '' }, false, legacy), false)
+    assert.equal(resolveFailOpen({ failOpen: 'maybe' }, false), false)
+    assert.equal(resolveFailOpen({ failOpen: {} }, false), false)
+    assert.equal(resolveFailOpen({ failOpen: NaN }, false), false)
+  })
+
+  it('keeps 0/1 working, because that is how a boolean survives a database', () => {
+    assert.equal(resolveFailOpen({ failOpen: 1 }, false), true)
+    assert.equal(resolveFailOpen({ failOpen: 0 }, true), false)
+    assert.equal(resolveFailOpen({ failClosed: 1 }, true, legacy), false)
+  })
+
+  it('never lets a junk CLIENT default land on fail open', () => {
+    assert.equal(resolveFailOpen({}, null), false)
+    assert.equal(resolveFailOpen({}, 'false'), false)
+    assert.equal(resolveFailOpen({}, 'true'), true)
+  })
+
+  it('survives a caller who passes no options object at all', () => {
+    assert.equal(resolveFailOpen(null, false), false)
+    assert.equal(resolveFailOpen('nonsense', false), false)
+  })
+})
+
+// ── guard.wrap ──────────────────────────────────────────────────────────────
+
+describe('guard.wrap — when Ciphyrs is unreachable', () => {
+  it('blocks by default: the LLM is never called', async () => {
+    const c = downGuard(clientWith())
+    let ran = false
+    await assert.rejects(c.guard.wrap('hi', async () => { ran = true; return 'out' }), CiphyrsError)
+    assert.equal(ran, false)
+  })
+
+  it('runs the LLM when the CALL asks to fail open, and says the check was skipped', async () => {
+    const c = downGuard(clientWith())
+    const r = await c.guard.wrap('hi', async () => 'out', { failOpen: true })
+    assert.equal(r.blocked, false)
+    assert.equal(r.output, 'out')
+    assert.equal(r.failedOpen, true, 'an un-decided allow must not look like a decided one')
+  })
+
+  it('runs the LLM when the CLIENT asks to fail open', async () => {
+    const c = downGuard(clientWith({ failOpen: true }))
+    const r = await c.guard.wrap('hi', async () => 'out')
+    assert.equal(r.output, 'out')
+    assert.equal(r.failedOpen, true)
+  })
+
+  it('lets a call close a fail-open client back down', async () => {
+    const c = downGuard(clientWith({ failOpen: true }))
+    let ran = false
+    await assert.rejects(c.guard.wrap('hi', async () => { ran = true; return 'out' }, { failOpen: false }))
+    assert.equal(ran, false)
+  })
+
+  it('ignores the legacy failClosed key — it has never meant anything here', async () => {
+    // `failClosed: false` copy-pasted from a protectTool call site. On
+    // protectTool it is a written-down fail-open posture; on guard.wrap it has
+    // always been inert (check() whitelists its fields), and starting to read
+    // it would silently uncover the LLM for anyone who moved the key across.
+    const c = downGuard(clientWith())
+    let ran = false
+    await assert.rejects(
+      c.guard.wrap('hi', async () => { ran = true; return 'out' }, { failClosed: false }), CiphyrsError)
+    assert.equal(ran, false, 'a legacy key from another surface turned fail-closed off')
+  })
+
+  it('does not mark a healthy round-trip as failedOpen', async () => {
+    const c = clientWith({ failOpen: true })
+    c.guard.check = async () => ({ decision: 'allow', detections: [], decision_id: 'd-1' })
+    const r = await c.guard.wrap('hi', async () => 'out')
+    assert.equal(r.failedOpen, undefined)
+  })
+
+  it('still blocks on a real block verdict while failing open', async () => {
+    // Fail-open is about unreachability, not about ignoring decisions.
+    const c = clientWith({ failOpen: true })
+    c.guard.check = async () => ({ decision: 'block', reason: 'injection', detections: [], decision_id: 'd-2' })
+    let ran = false
+    const r = await c.guard.wrap('hi', async () => { ran = true; return 'out' })
+    assert.equal(r.blocked, true)
+    assert.equal(ran, false)
+  })
+})
+
+// ── scan.protect ────────────────────────────────────────────────────────────
+
+describe('scan.protect — when the masker is unreachable', () => {
+  it('blocks by default: raw text never reaches the LLM', async () => {
+    const c = downMasker(clientWith())
+    let seen = null
+    await assert.rejects(c.scan.protect('my ssn is 123-45-6789', async (t) => { seen = t; return 'ok' }),
+      CiphyrsError)
+    assert.equal(seen, null, 'unmasked PII was handed to the LLM during an outage')
+  })
+
+  it('sends raw text only when explicitly asked, and marks the result', async () => {
+    const c = downMasker(clientWith())
+    const warn = console.warn; const warned = []
+    console.warn = (m) => warned.push(m)
+    try {
+      const r = await c.scan.protect('my ssn is 123-45-6789', async (t) => `saw: ${t}`, { failOpen: true })
+      assert.equal(r.output, 'saw: my ssn is 123-45-6789')
+      assert.equal(r.failedOpen, true)
+      assert.equal(r.sessionId, null)
+      assert.ok(warned.some((m) => /UNMASKED/.test(m)),
+        'the one fail-open path that leaks PII must say so out loud')
+    } finally { console.warn = warn }
+  })
+
+  it('honours the client-level posture', async () => {
+    const c = downMasker(clientWith({ failOpen: true }))
+    const warn = console.warn; console.warn = () => {}
+    try {
+      const r = await c.scan.protect('hi', async (t) => t)
+      assert.equal(r.failedOpen, true)
+    } finally { console.warn = warn }
+  })
+
+  it('lets a call close a fail-open client back down', async () => {
+    const c = downMasker(clientWith({ failOpen: true }))
+    let seen = null
+    await assert.rejects(c.scan.protect('hi', async (t) => { seen = t; return 'ok' }, { failOpen: false }))
+    assert.equal(seen, null)
+  })
+
+  it('ignores the legacy failClosed key — raw text still never reaches the LLM', async () => {
+    // This is the worst place for the legacy key to become live: on
+    // scan.protect, "fail open" means handing the customer's unmasked PII to
+    // their model. Nobody who copy-pasted an inert key from a protectTool call
+    // site asked for that.
+    const c = downMasker(clientWith())
+    let seen = null
+    await assert.rejects(
+      c.scan.protect('my ssn is 123-45-6789', async (t) => { seen = t; return 'ok' }, { failClosed: false }),
+      CiphyrsError)
+    assert.equal(seen, null, 'a legacy key from another surface sent unmasked PII to the LLM')
+  })
+
+  it('does not mark a healthy round-trip as failedOpen', async () => {
+    const c = clientWith()
+    c.scan.mask = async () => ({ maskedText: '[PERSON_1]', sessionId: 's-1', entitiesFound: [] })
+    c.scan.restore = async () => ({ restoredText: 'Jane', tokensRestored: 1, purged: true })
+    const r = await c.scan.protect('Jane', async (t) => t)
+    assert.equal(r.failedOpen, undefined)
+    assert.equal(r.output, 'Jane')
+  })
+})
+
+// ── All three, one outage ───────────────────────────────────────────────────
+
+describe('the whole client under one outage', () => {
+  const stub = (c) => { downGuard(c); downMasker(c); c._toolCheck = async () => OUTAGE(); return c }
+
+  it('every entry point refuses by default', async () => {
+    const { protectTool, ToolBlocked } = await import('./protect-tool.js')
+    const c = stub(clientWith())
+    const ran = { tool: false, llm: false, mask: false }
+    const tool = protectTool(c, { agent: 'billing-bot', name: 'refund' }, async () => { ran.tool = true })
+
+    await assert.rejects(tool({ amount: 1 }), ToolBlocked)
+    await assert.rejects(c.guard.wrap('hi', async () => { ran.llm = true; return 'o' }))
+    await assert.rejects(c.scan.protect('hi', async () => { ran.mask = true; return 'o' }))
+    assert.deepEqual(ran, { tool: false, llm: false, mask: false })
+  })
+
+  it('one client-level failOpen moves every entry point together', async () => {
+    const { protectTool } = await import('./protect-tool.js')
+    const c = stub(clientWith({ failOpen: true }))
+    const warn = console.warn; console.warn = () => {}
+    try {
+      const ran = { tool: false, llm: false, mask: false }
+      await protectTool(c, { agent: 'billing-bot', name: 'refund' }, async () => { ran.tool = true })({ amount: 1 })
+      await c.guard.wrap('hi', async () => { ran.llm = true; return 'o' })
+      await c.scan.protect('hi', async () => { ran.mask = true; return 'o' })
+      assert.deepEqual(ran, { tool: true, llm: true, mask: true })
+    } finally { console.warn = warn }
+  })
+
+  it('the legacy failClosed key moves protectTool and ONLY protectTool', async () => {
+    // One key, three surfaces, and it is honoured on the one where it shipped.
+    // Both halves matter: dropping it on protectTool breaks callers who wrote
+    // their posture down, and honouring it on the other two silently uncovers
+    // callers who moved an inert key across.
+    const { protectTool } = await import('./protect-tool.js')
+    const c = stub(clientWith())
+    const ran = { tool: false, llm: false, mask: false }
+    await protectTool(c, { agent: 'billing-bot', name: 'refund', failClosed: false },
+      async () => { ran.tool = true })({ amount: 1 })
+    await assert.rejects(c.guard.wrap('hi', async () => { ran.llm = true; return 'o' }, { failClosed: false }))
+    await assert.rejects(c.scan.protect('hi', async () => { ran.mask = true; return 'o' }, { failClosed: false }))
+    assert.deepEqual(ran, { tool: true, llm: false, mask: false })
+  })
+})
+
+// ── Anchored to the real transport ──────────────────────────────────────────
+
+describe('a real transport failure reaches the posture', () => {
+  it('guard.wrap fails closed on a refused connection, not just on a stubbed throw', async () => {
+    // The stubs above assume request() surfaces an outage as a thrown error
+    // once its retries are spent. This one pays the retry budget to prove it.
+    //
+    // fetch is still stubbed rather than allowed to dial a dead port: a real
+    // dial is a socket, and this suite does not open sockets. The swap is the
+    // one thing this file does to a global — the socket guard is what makes
+    // getting the restore wrong a failed run instead of a production request.
+    const realFetch = globalThis.fetch
+    globalThis.fetch = async () => { throw new Error('ECONNREFUSED') }
+    try {
+      const c = clientWith()
+      let ran = false
+      await assert.rejects(c.guard.wrap('hi', async () => { ran = true; return 'o' }), CiphyrsError)
+      assert.equal(ran, false)
+    } finally { globalThis.fetch = realFetch }
+  })
+})
+
+// ── The suite may not touch the network ─────────────────────────────────────
+//
+// This file used to POST to https://www.ciphyrs.com/v1/agent-inventory/announce
+// twice on every run, from the tool-inventory announce protectTool queues at
+// wrap time. It fired 2s later, on the real fetch, after the last test had
+// restored it — so no stub, in any order, could have stopped it.
+
+describe('no test reaches the network', () => {
+  it('a real client is never pointed at production', () => {
+    const c = clientWith()
+    assert.equal(c._baseUrl, SENTINEL_BASE)
+    assert.ok(!/ciphyrs\.com/.test(c._baseUrl), 'a test client was aimed at the live service')
+  })
+
+  it('wrapping a tool queues no announce at all', () => {
+    // Not "the announce fails harmlessly" — there is no timer to fire. This is
+    // the structural half; the socket guard is the backstop.
+    const c = clientWith()
+    assert.equal(typeof c._announceTools, 'undefined',
+      'protectTool would queue a debounced announce against this client')
+  })
+
+  it('the guard actually blocks a socket, and fails the run when one is opened', () => {
+    const message = expectBlocked(() => net.connect({ host: 'www.ciphyrs.com', port: 443 }))
+    assert.match(message, /www\.ciphyrs\.com:443/)
+    assert.match(message, /never reach the network/)
+  })
+
+  it('records nothing when the suite behaves', () => {
+    // expectBlocked() above un-records its own deliberate attempt, so anything
+    // left here is a real escape — and the guard's exit handler turns a
+    // non-empty list into a non-zero exit code even for an attempt whose
+    // caller swallowed the error.
+    assert.deepEqual(networkAttempts(), [])
+  })
+})