@ciphyrshq/sdk 3.0.0 → 3.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ciphyrshq/sdk",
-  "version": "3.0.0",
+  "version": "3.0.1",
   "description": "Official JavaScript / TypeScript SDK for the Ciphyrs PII Shield API",
   "type": "module",
   "main": "./src/index.js",
@@ -16,13 +16,29 @@
     "./secret-detector": "./src/secret-detector.js",
     "./eval-runner": "./src/eval-runner.js"
   },
-  "files": ["src", "types.d.ts"],
-  "keywords": ["pii", "privacy", "masking", "llm", "ciphyrs", "gdpr", "dpdp", "sdk"],
+  "files": [
+    "src",
+    "!src/*.test.js",
+    "!src/*.test-helper.js",
+    "types.d.ts"
+  ],
+  "keywords": [
+    "pii",
+    "privacy",
+    "masking",
+    "llm",
+    "ciphyrs",
+    "gdpr",
+    "dpdp",
+    "sdk"
+  ],
   "license": "MIT",
-  "engines": { "node": ">=18" },
+  "engines": {
+    "node": ">=18"
+  },
   "repository": {
     "type": "git",
-    "url": "https://github.com/praveen190/Ciphyrs.git",
+    "url": "git+https://github.com/praveen190/Ciphyrs.git",
     "directory": "packages/sdk"
   },
   "homepage": "https://ciphyrs.com",

package/src/client.test.js

@@ -1,99 +0,0 @@
-/**
- * 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/fail-posture.test.js

@@ -1,385 +0,0 @@
-/**
- * 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(), [])
-  })
-})

package/src/no-network.test-helper.js

@@ -1,108 +0,0 @@
-// ═══════════════════════════════════════════════════════════════════════════
-//  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]
-}