@ciphyrshq/sdk 2.6.0 → 3.0.0

package/src/protect-tool.js

@@ -0,0 +1,362 @@
+// ═══════════════════════════════════════════════════════════════════════════
+//  protectTool — V60
+//
+//  Tool-call authorization wrapper for any async function. Mirrors the
+//  Python SDK's @protect_tool decorator. Use it to gate a tool function so
+//  that, before it runs, Ciphyrs evaluates the customer's per-agent /
+//  per-tool rules and decides whether the call is allowed, blocked, or
+//  needs human approval.
+//
+//  Usage:
+//
+//      import { CiphyrsClient, protectTool } from '@ciphyrshq/sdk'
+//
+//      const client = new CiphyrsClient({ apiKey: 'cyp_live_...' })
+//
+//      // Async tool
+//      const refundPayment = protectTool(client, {
+//        agent: 'billing-bot',
+//        name:  'refund_payment',
+//      }, async ({ customerId, amount }) => {
+//        return stripe.refunds.create({ customer: customerId, amount })
+//      })
+//
+//      // Now this call goes through Ciphyrs first:
+//      await refundPayment({ customerId: 'cus_abc', amount: 85000 })
+//      // -> if a rule matches, throws ToolBlocked or pauses for approval.
+//      // -> if allowed, the underlying function runs.
+//
+//  Failure semantics: fail-CLOSED by default. If Ciphyrs cannot be reached,
+//  the tool does NOT run and ToolBlocked is thrown. This is a deliberate
+//  change of a published default — protectTool used to fail OPEN, so an
+//  outage of ours ran the customer's tool unauthorised, while guard.wrap and
+//  scan.protect on the same client refused to proceed under the identical
+//  outage. This is the path that moves money, so it is the one that gets the
+//  safe default, and all three now read the same option:
+//
+//      protectTool(client, { agent, failOpen: true }, fn)   // per call
+//      new CiphyrsClient({ apiKey, failOpen: true })        // per client
+//
+//  { failClosed: true } and { failClosed: false } both still mean exactly
+//  what they did before, so nobody who already wrote down a posture is moved.
+//  That legacy key is read HERE and nowhere else — it is the only surface it
+//  ever shipped on, and on guard.wrap and scan.protect it has always been
+//  inert. A null or unreadable posture on either spelling means "not chosen",
+//  which is fail closed; only a value that unmistakably says fail open does.
+// ═══════════════════════════════════════════════════════════════════════════
+import { activeIds, activeSpanKind } from './context.js'
+import { resolveFailOpen, FAIL_OPEN_HINT } from './fail-posture.js'
+
+export class ToolBlocked extends Error {
+  constructor(action, reason, opts = {}) {
+    super(`[ciphyrs] tool blocked (${action}): ${reason}`)
+    this.name = 'ToolBlocked'
+    this.action = action
+    this.reason = reason
+    this.ruleId = opts.ruleId
+    this.ruleName = opts.ruleName
+    this.decisionId = opts.decisionId
+  }
+}
+
+export class ToolApprovalTimeout extends ToolBlocked {
+  constructor(reason) {
+    super('timeout', reason)
+    this.name = 'ToolApprovalTimeout'
+  }
+}
+
+/**
+ * Wrap an async function with Ciphyrs tool-call authorization.
+ *
+ * @param {object} client            CiphyrsClient instance
+ * @param {object} opts
+ * @param {string} opts.agent        Agent name (used to scope rules)
+ * @param {string} [opts.name]       Tool name reported to Ciphyrs (default: fn.name)
+ * @param {boolean} [opts.failOpen]  If true, run the tool anyway when Ciphyrs is
+ *                                   unreachable. Defaults to the client's posture,
+ *                                   which itself defaults to FALSE (fail closed).
+ * @param {boolean} [opts.failClosed]
+ *                                   Legacy spelling of the same switch, honoured in
+ *                                   both directions (`false` still means fail open).
+ * @param {number} [opts.pollIntervalMs=1000]
+ *                                   Approval poll interval
+ * @param {number} [opts.maxPollSeconds]
+ *                                   Hard cap on poll duration; defaults to whatever the rule says
+ * @param {(args: any) => any} fn    The async tool function to wrap
+ * @returns {(args: any) => Promise<any>}
+ */
+export function protectTool(client, opts, fn) {
+  // Validate BEFORE destructuring: `name = fn.name` below dereferences fn, so
+  // with the check underneath it the caller got "Cannot read properties of
+  // null (reading 'name')" instead of the message written for them — and the
+  // check never ran at all. That is the error for the likeliest misuse of a
+  // three-argument function: passing the arguments in the wrong order.
+  if (typeof fn !== 'function') throw new Error('protectTool: a function is required as the third argument')
+
+  const {
+    agent,
+    name = fn.name || 'anonymous',
+    pollIntervalMs = 1000,
+    maxPollSeconds,
+  } = opts || {}
+
+  if (!agent) throw new Error('protectTool: opts.agent is required')
+
+  // Resolved at wrap time, not per invocation: the wrapped function's
+  // signature belongs to the customer's tool, so there is nowhere to put a
+  // per-invocation option without colliding with its arguments. The wrap site
+  // IS the per-call level here; the client supplies the fleet-wide default.
+  // `legacyFailClosed` is opted into HERE and nowhere else: protectTool is the
+  // only surface the legacy key ever shipped on, so it is the only surface
+  // where honouring it preserves behaviour rather than creating new behaviour.
+  const failOpen = resolveFailOpen(opts, client?._failOpen, { legacyFailClosed: true })
+
+  // Announce this tool to the inventory at wrap time (debounced per client,
+  // best-effort). The dashboard sees — and can write allowlist policy for —
+  // every decorated tool seconds after the agent process boots, before any
+  // traffic. Without this, rarely-called tools stay invisible until their
+  // first invocation, which makes default-deny allowlists incomplete.
+  queueToolAnnounce(client, agent, {
+    name,
+    description: opts?.description,
+  })
+
+  return async function protectedTool(...args) {
+    const argsPayload = serializeArgs(args)
+
+    // WHICH STEP is asking. The gateway's trust.001 rule ("tool ran without a
+    // tool-check") correlates an exported tool span against the gate call that
+    // authorised it by span id — see services/api-gateway/src/lib/trust-checks.js,
+    // unverifiedToolSpans() and spanCorrelatedAgents(). Field names are the
+    // gateway's: POST /v1/guard/tool-check destructures `trace_id` and
+    // `span_id` off the body. Read producerIds() for why the span id is sent
+    // so rarely, and why sending the wrong one is worse than sending none.
+    const { trace_id, span_id } = producerIds()
+
+    let verdict
+    try {
+      verdict = await client._toolCheck({
+        agent_name: agent,
+        tool_name:  name,
+        args:       argsPayload,
+        // Omitted, never invented and never borrowed from a span of another
+        // kind: an id that is not this tool call's own would not merely fail to
+        // correlate, it would tell trust.001 that correlation IS possible for
+        // this agent and let it judge spans it can never match — a
+        // high-severity accusation against a compliant app.
+        ...(trace_id ? { trace_id } : {}),
+        ...(span_id  ? { span_id }  : {}),
+      })
+    } catch (err) {
+      if (!failOpen) {
+        throw new ToolBlocked('error',
+          `Ciphyrs unreachable, so the tool did not run: ${err.message}. ` +
+          `Tool execution fails closed by default. ${FAIL_OPEN_HINT}`)
+      }
+      // Fail open — explicitly asked for.
+      return fn(...args)
+    }
+
+    if (verdict.action === 'require_approval') {
+      verdict = await pollApproval(
+        client, verdict.approval_id,
+        pollIntervalMs,
+        (maxPollSeconds || verdict.approval_timeout_seconds || 300) * 1000,
+      )
+    }
+
+    enforce(verdict, failOpen)
+    // The tool runs on the args the POLICY approved, which are not always the
+    // args the caller passed. enforce() treats redact_args as permitted; if
+    // the redaction were not applied here too, a redact_args rule would report
+    // success on the dashboard while the tool received the raw value — the
+    // exact opposite of what the customer configured.
+    return fn(...applyRedaction(args, verdict))
+  }
+}
+
+// ─── Internals ─────────────────────────────────────────────────────────────
+
+// `gs_<hex>` is what routes/guard.js mints when the caller sends no span id,
+// and lib/trust-checks.js reads a stored id of that shape as proof that the
+// producer did NOT say which step it was asking about. See producerIds().
+const GATEWAY_MINTED_SPAN_ID = /^gs_[0-9a-f]{1,32}$/
+
+// The span kinds the gateway will ingest AS a tool span — TOOL_KINDS in
+// lib/trust-checks.js. Only a span of one of these kinds is the span this tool
+// call will be judged by, so only its id is worth putting on the wire.
+const TOOL_SPAN_KINDS = new Set(['tool', 'tool_use', 'tool_call'])
+
+/**
+ * The ids to attribute this gate call to.
+ *
+ * `trace_id` whenever a trace is open: it is always true, and it is what the
+ * batch read uses to find this agent's records at all.
+ *
+ * `span_id` ONLY when the ambient span is a TOOL span — i.e. when the id we
+ * would send is the id of the span this tool call will actually export.
+ * protectTool emits no span of its own; it wraps a function, it does not trace
+ * it. So the ambient span is normally the enclosing AGENT span, and sending
+ * that id does damage in both directions at once:
+ *
+ *   - unverifiedToolSpans() exonerates a tool span only when a record carries
+ *     the SAME span id. An agent-span id can never equal a tool-span id, so
+ *     the exact-match path stays dead — exactly as dead as sending nothing.
+ *   - spanCorrelatedAgents() treats any non-`gs_` id as proof that this
+ *     agent's spans and its gate calls CAN be matched exactly. That moves the
+ *     agent out of `agent_not_span_correlated` — trust.001's abstention, "we
+ *     refuse to judge you" — and into judgement on the (agent, tool) ±2-minute
+ *     fallback, a correlation nothing has ever validated, for a high-severity
+ *     enforcement_bypass accusation.
+ *
+ * So the wrong id converts abstention into judgement on a guess. Sending
+ * nothing keeps the abstention, which is the honest posture for a wrapper that
+ * does not know which span it is inside. A remote parent never qualifies
+ * either: its kind does not travel in baggage, and it is the CALLER's span,
+ * not the span this tool call exports.
+ */
+function producerIds() {
+  const { trace_id, span_id } = activeIds()
+  // `gs_…` is what routes/guard.js mints when the caller sends no span id, and
+  // lib/trust-checks.js reads a stored id of that shape as proof that the
+  // producer did NOT say which step it was asking about. context.js can hand
+  // back a span id carried in inbound Ciphyrs baggage — an arbitrary string
+  // chosen by whoever called us — so echoing a gateway-shaped one back would
+  // claim the producer chose an id that says correlation is impossible.
+  const namesThisToolSpan =
+    TOOL_SPAN_KINDS.has(activeSpanKind())
+    && !!span_id && !GATEWAY_MINTED_SPAN_ID.test(span_id)
+
+  return {
+    trace_id: trace_id || undefined,
+    span_id: namesThisToolSpan ? span_id : undefined,
+  }
+}
+
+// Startup announce: collect tools per (client, agent) as they're wrapped,
+// flush once 2s after the last registration. WeakMap so we never keep a
+// client alive; timer is unref()'d so it never holds the process open;
+// failures are swallowed — announce is telemetry, not enforcement.
+const _announceRegistry = new WeakMap() // client -> { agents: Map<agent, Map<name, meta>>, timer }
+
+function queueToolAnnounce(client, agent, tool) {
+  if (!client || typeof client._announceTools !== 'function') return
+  let entry = _announceRegistry.get(client)
+  if (!entry) {
+    entry = { agents: new Map(), timer: null }
+    _announceRegistry.set(client, entry)
+  }
+  if (!entry.agents.has(agent)) entry.agents.set(agent, new Map())
+  entry.agents.get(agent).set(tool.name, {
+    name: tool.name,
+    description: tool.description ? String(tool.description).slice(0, 1000) : undefined,
+  })
+
+  if (entry.timer) clearTimeout(entry.timer)
+  entry.timer = setTimeout(() => {
+    entry.timer = null
+    const batches = [...entry.agents.entries()]
+    entry.agents = new Map()
+    for (const [agentName, tools] of batches) {
+      client._announceTools(agentName, [...tools.values()]).catch(() => {})
+    }
+  }, 2000)
+  if (typeof entry.timer.unref === 'function') entry.timer.unref()
+}
+
+function serializeArgs(args) {
+  // args is the rest-array. If the function is called with one object,
+  // unwrap it so rules can reference fields by name (`args.amount`).
+  // Otherwise return the positional list under `args`.
+  if (args.length === 1 && args[0] && typeof args[0] === 'object' && !Array.isArray(args[0])) {
+    return safeClone(args[0])
+  }
+  return { args: args.map(safeClone) }
+}
+
+function safeClone(v) {
+  try {
+    return JSON.parse(JSON.stringify(v, (_k, val) => {
+      if (typeof val === 'function') return `<fn:${val.name || 'anon'}>`
+      if (typeof val === 'undefined') return null
+      if (typeof val === 'bigint') return val.toString()
+      return val
+    }))
+  } catch {
+    return `<non-serializable: ${typeof v}>`
+  }
+}
+
+async function pollApproval(client, approvalId, intervalMs, maxMs) {
+  const deadline = Date.now() + maxMs
+  while (Date.now() < deadline) {
+    await sleep(intervalMs)
+    let r
+    try { r = await client._approvalStatus(approvalId) }
+    catch { continue }
+    if (r.status === 'approved') return { action: 'allow', reason: r.reason || 'approved' }
+    // 'cancelled' is in the agent_approvals CHECK constraint alongside the
+    // other two. Omitting it did not let anything through — the loop just
+    // failed to notice the decision and waited out the window — but the agent
+    // then stalled for the full approval timeout on a call already withdrawn,
+    // and reported it as a timeout rather than a cancellation.
+    if (r.status === 'denied' || r.status === 'timeout' || r.status === 'cancelled') {
+      throw new ToolBlocked(r.status, r.reason || r.status)
+    }
+  }
+  throw new ToolApprovalTimeout(`No approval within ${Math.round(maxMs/1000)}s`)
+}
+
+/**
+ * Rebuild the call arguments from a redact_args verdict.
+ *
+ * Has to mirror serializeArgs() exactly, because that is the shape the server
+ * redacted: a lone object went up unwrapped, so the redaction comes back
+ * unwrapped; positional arguments went up under `args`, so they come back
+ * there too.
+ */
+function applyRedaction(args, verdict) {
+  const action = verdict.action || verdict.decision
+  if (action !== 'redact_args') return args
+
+  const redacted = verdict.redacted_args
+  if (!redacted || typeof redacted !== 'object') {
+    // The gateway populates redacted_args whenever it returns this action, so
+    // arriving here means the verdict is malformed. Running the tool on the
+    // originals would be the silent-leak bug this function exists to close,
+    // and there is no safe way to guess what should have been masked.
+    throw new ToolBlocked('redact_args',
+      'policy required argument redaction but the verdict carried no redacted_args')
+  }
+
+  const singleObject = args.length === 1 && args[0]
+    && typeof args[0] === 'object' && !Array.isArray(args[0])
+  if (singleObject) return [redacted]
+  if (Array.isArray(redacted.args)) return redacted.args
+  throw new ToolBlocked('redact_args',
+    'policy required argument redaction but the verdict did not match the call shape')
+}
+
+function enforce(verdict, failOpen = false) {
+  const declared = verdict.action || verdict.decision
+  // A response carrying no verdict at all is a NON-DECISION. Defaulting it to
+  // 'allow' is how a misconfigured proxy or a half-deployed gateway turns an
+  // outage into blanket permission — the failure the inline proxy already
+  // shipped once (HTTP 200 + decision:'allow' on internal error). A caller who
+  // asked to fail open has asked for that too; everyone else gets the block.
+  if (!declared && !failOpen) {
+    throw new ToolBlocked('error',
+      'Ciphyrs returned no verdict — neither action nor decision present — so the tool did not run. ' +
+      FAIL_OPEN_HINT)
+  }
+  const action = declared || 'allow'
+  if (action === 'allow' || action === 'log_only' || action === 'redact_args') return
+  throw new ToolBlocked(action, verdict.reason || 'blocked by Ciphyrs rule', {
+    ruleId: verdict.rule_id,
+    ruleName: verdict.rule_name,
+    decisionId: verdict.decision_id,
+  })
+}
+
+const sleep = (ms) => new Promise(r => setTimeout(r, ms))