From 2b828ca2c5d669db79bf487a8ca0c2ce280674f2 Mon Sep 17 00:00:00 2001 From: Danny Avila Date: Mon, 16 Nov 2026 22:37:13 -0500 Subject: [PATCH] =?UTF-8?q?=F0=9F=9B=81=20feat:=20Apply=20Host=20Provider-?= =?UTF-8?q?Text=20Protection=20to=20Remote=20SDK=20Runs=20(#18240)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * feat: bridge host provider-text policy to remote SDK runs * build: consume published agents 4.2.7 for remote policy services --- api/package.json | 2 +- bun.lock | 6 +- docs/sdk/agents.md | 119 +++++++-- examples/sdk-runtime/README.md | 14 + examples/sdk-runtime/agent.cjs | 10 + examples/sdk-runtime/benchmark.cjs | 38 ++- package-lock.json | 10 +- packages/api/package.json | 2 +- .../api/src/agents/remoteSdk/bridge.spec.ts | 127 +++++++++ packages/api/src/agents/remoteSdk/client.ts | 21 +- .../api/src/agents/remoteSdk/policy.spec.ts | 240 ++++++++++++++++++ packages/api/src/agents/remoteSdk/policy.ts | 93 +++++++ .../runtime.cache_integration.spec.ts | 67 +++++ packages/api/src/agents/remoteSdk/sealed.ts | 118 +++++++++ packages/api/src/agents/remoteSdk/server.ts | 19 +- packages/api/src/agents/remoteSdk/types.ts | 18 +- packages/api/src/sdk.ts | 1 + 17 files changed, 870 insertions(+), 35 deletions(-) create mode 100644 packages/api/src/agents/remoteSdk/policy.spec.ts create mode 100644 packages/api/src/agents/remoteSdk/policy.ts create mode 100644 packages/api/src/agents/remoteSdk/sealed.ts diff --git a/api/package.json b/api/package.json index 539f459aae..1e6b2fb786 100644 --- a/api/package.json +++ b/api/package.json @@ -40,7 +40,7 @@ "@azure/storage-blob": "^12.30.0", "@google/genai": "^2.8.0", "@keyv/redis": "5.1.6", - "@librechat/agents": "^4.2.6", + "@librechat/agents": "^4.2.7", "@librechat/api": "*", "@librechat/data-schemas": "*", "@microsoft/microsoft-graph-client": "^3.0.7", diff --git a/bun.lock b/bun.lock index 3b54bfb838..877a6d2176 100644 --- a/bun.lock +++ b/bun.lock @@ -55,7 +55,7 @@ "@azure/storage-blob": "^12.30.0", "@google/genai": "^2.8.0", "@keyv/redis": "5.1.6", - "@librechat/agents": "^4.2.6", + "@librechat/agents": "^4.2.7", "@librechat/api": "*", "@librechat/data-schemas": "*", "@microsoft/microsoft-graph-client": "^3.0.7", @@ -378,7 +378,7 @@ "@azure/identity": "^4.14.0", "@azure/storage-blob": "^12.30.0", "@keyv/redis": "5.1.6", - "@librechat/agents": "^4.2.6", + "@librechat/agents": "^4.2.7", "@librechat/data-schemas": "*", "@modelcontextprotocol/sdk": "^1.32.1", "@opentelemetry/api": "^1.9.0", @@ -1603,7 +1603,7 @@ "@lezer/lr": ["@lezer/lr@1.4.2", "", { "dependencies": { "@lezer/common": "^1.0.0" } }, "sha512-pu0K1jCIdnQ12aWNaAVU5bzi7Bd1w54J3ECgANPmYLtQKP0HBj2cE/5coBD66MT10xbtIuUr7tg0Shbsvk0mDA=="], - "@librechat/agents": ["@librechat/agents@4.2.6", "", { "dependencies": { "@anthropic-ai/sdk": "^0.115.0", "@aws-sdk/client-bedrock-runtime": "^3.1075.0", "@langchain/anthropic": "1.5.2", "@langchain/aws": "^1.4.2", "@langchain/core": "1.2.8", "@langchain/deepseek": "^1.1.3", "@langchain/google-common": "2.2.0", "@langchain/google-gauth": "2.2.0", "@langchain/google-genai": "2.2.0", "@langchain/google-vertexai": "2.2.0", "@langchain/langgraph": "1.4.8", "@langchain/mistralai": "^1.2.0", "@langchain/openai": "1.5.8", "@langchain/textsplitters": "^1.0.1", "@langchain/xai": "^1.4.3", "@langfuse/core": "^5.10.1", "@langfuse/langchain": "^5.10.1", "@langfuse/otel": "^5.10.1", "@langfuse/tracing": "^5.10.1", "@opentelemetry/context-async-hooks": "^2.9.0", "@opentelemetry/sdk-node": "^0.220.0", "@types/diff": "^7.0.2", "ai-tokenizer": "^1.0.6", "axios": "^1.20.0", "cheerio": "^1.2.0", "diff": "^9.0.0", "dotenv": "^16.4.7", "https-proxy-agent": "^7.0.6", "mathjs": "^15.2.0", "nanoid": "^3.3.18", "okapibm25": "^1.4.1", "openai": "^6.46.0", "reova": "^0.4.1", "socks-proxy-agent": "^8.0.5", "uuid": "^11.1.1", "zod": "4.6.7", "zod-to-json-schema": "3.25.2" }, "peerDependencies": { "@anthropic-ai/sandbox-runtime": "^0.0.78" }, "optionalPeers": ["@anthropic-ai/sandbox-runtime"] }, "sha512-UWp0UjIrXIt/tdO5BWDaTRpVQFN6yEHwmDdAregs1yHN/X/8GHu2D3ParQB0ze3NR3nm7Mkps/K0VB476oA7UQ=="], + "@librechat/agents": ["@librechat/agents@4.2.7", "", { "dependencies": { "@anthropic-ai/sdk": "^0.115.0", "@aws-sdk/client-bedrock-runtime": "^3.1075.0", "@langchain/anthropic": "1.5.2", "@langchain/aws": "^1.4.2", "@langchain/core": "1.2.8", "@langchain/deepseek": "^1.1.3", "@langchain/google-common": "2.2.0", "@langchain/google-gauth": "2.2.0", "@langchain/google-genai": "2.2.0", "@langchain/google-vertexai": "2.2.0", "@langchain/langgraph": "1.4.8", "@langchain/mistralai": "^1.2.0", "@langchain/openai": "1.5.8", "@langchain/textsplitters": "^1.0.1", "@langchain/xai": "^1.4.3", "@langfuse/core": "^5.10.1", "@langfuse/langchain": "^5.10.1", "@langfuse/otel": "^5.10.1", "@langfuse/tracing": "^5.10.1", "@opentelemetry/context-async-hooks": "^2.9.0", "@opentelemetry/sdk-node": "^0.220.0", "@types/diff": "^7.0.2", "ai-tokenizer": "^1.0.6", "axios": "^1.20.0", "cheerio": "^1.2.0", "diff": "^9.0.0", "dotenv": "^16.4.7", "https-proxy-agent": "^7.0.6", "mathjs": "^15.2.0", "nanoid": "^3.3.18", "okapibm25": "^1.4.1", "openai": "^6.46.0", "reova": "^0.4.1", "socks-proxy-agent": "^8.0.5", "uuid": "^11.1.1", "zod": "4.6.7", "zod-to-json-schema": "3.25.2" }, "peerDependencies": { "@anthropic-ai/sandbox-runtime": "^0.0.78" }, "optionalPeers": ["@anthropic-ai/sandbox-runtime"] }, "sha512-j6TfPPZhiEHMFyT7xVc1y3Hh+w+l9YOkMf/0IlJU/GDoyH+DUyVElU9fjdmUVNSMcCHOQb0diHS7B9sQSofD8g=="], "@librechat/api": ["@librechat/api@workspace:packages/api"], diff --git a/docs/sdk/agents.md b/docs/sdk/agents.md index 8c6ea9d859..873bf1b358 100644 --- a/docs/sdk/agents.md +++ b/docs/sdk/agents.md @@ -154,27 +154,27 @@ acceptance target remains the main chat's functionality and experience, with mea Using native events and the native renderer proves only the behaviors tested below. Missing adapters and unverified behaviors remain release gates for products that depend on them. -| Main-chat capability | This bridge | Remaining work / verification | -| ----------------------------------------------------------- | --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | -| Saved agent identity, role authorization, picker | Reuses the existing registration and picker | Remote enrollment/discovery is not implemented; operators configure deployments. | -| Text and tool-step rendering, persistence | Verified with a minimal Run and a custom graph in real LibreChat | Deterministic models were used; repeat with production providers and representative workloads. | -| Reasoning, citations, rich/custom tool events | Native event transport is available | Provider-specific and rich-content end-to-end parity has not been verified. | -| Custom graph, nested SDK node, conditional refinement | Verified in another process | Broader graphs, parallel branches, and large checkpoints need workload acceptance tests. | -| Approval after browser reload and worker restart | Approve verified with host Mongo checkpoints | Edit/reject, ask-user questions, and repeated/batched interruptions need remote browser tests. | -| Stop and browser reconnection to an active job | Verified; stop reaches the worker abort signal and persists no error | Cancellation is cooperative and cannot undo completed tool effects. | -| Host-worker connection recovery | Opt-in same-worker live reattachment; durable terminal replay after restart | No host-process adoption, live cross-worker migration, or arbitrary in-flight graph restart. Started executions never automatically rerun. | -| Model/PII/provider-text protection | Remote execution is blocked when these host policies are active | A supported host policy adapter is required before protected deployments can enable remote execution. | -| Stream circuit breakers and tool-policy hooks | Forwarded to the worker; hook failure stops execution | Domain tools must also authorize signed caller identity; trusted factories must retain the supplied adapters. | -| Agent-builder model, parameters, tools, capabilities | Name/instructions/identity are passed; worker owns the graph/model/tools | Other builder settings are not automatically applied. A runtime capability/configuration contract is needed to make controls authoritative. | -| Host MCP, web/code/browser tools, user tool credentials | Authorized root-agent schema tools execute through host RPC | Host credentials remain local; child-agent authorization and broader host-service parity remain separate integrations. | -| Uploaded files, generated artifacts, download authorization | Message data can cross the wire | Host file services, sandbox storage, and artifact authorization do not have remote adapters; attachment/file parity is not established. | -| Live steering and mid-stream preemption | Not integrated | A remote execution-control adapter and acceptance tests are required. | -| Foreground/nested/detached subagents | Worker may construct its own SDK graph | Native configured compositions are rejected; detached child checkpoint threads/context/usage sinks are not integrated. | -| Context pruning, compaction, summaries, cache/fading policy | Worker can use SDK features; terminal context metadata is returned | Host configuration and continuation policy are not automatically installed on the worker. Main-chat behavioral/performance parity is not established. | -| Token usage, cost/balance accounting | Native model events can be transported | Arbitrary worker model attribution and nested usage/balance enforcement need an explicit contract and tests; do not assume billing parity. | -| Tracing and tenant trace/export/redaction policy | Worker can configure SDK tracing itself | Host tracing callbacks and tenant export policy are not automatically inherited. Correlated, policy-safe tracing remains an integration gap. | -| Schedules/background/Responses callers | The bridge returns a Run through the common execution seam | Full lifecycle acceptance for these callers has not been performed. | -| Console Assistant and Schema Advisor | No product cutover in this change | Wire Schema Advisor, close its required gaps, then adopt shared chat components and compare performance. | +| Main-chat capability | This bridge | Remaining work / verification | +| ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| Saved agent identity, role authorization, picker | Reuses the existing registration and picker | Remote enrollment/discovery is not implemented; operators configure deployments. | +| Text and tool-step rendering, persistence | Verified with a minimal Run and a custom graph in real LibreChat | Deterministic models were used; repeat with production providers and representative workloads. | +| Reasoning, citations, rich/custom tool events | Native event transport is available | Provider-specific and rich-content end-to-end parity has not been verified. | +| Custom graph, nested SDK node, conditional refinement | Verified in another process | Broader graphs, parallel branches, and large checkpoints need workload acceptance tests. | +| Approval after browser reload and worker restart | Approve verified with host Mongo checkpoints | Edit/reject, ask-user questions, and repeated/batched interruptions need remote browser tests. | +| Stop and browser reconnection to an active job | Verified; stop reaches the worker abort signal and persists no error | Cancellation is cooperative and cannot undo completed tool effects. | +| Host-worker connection recovery | Opt-in same-worker live reattachment; durable terminal replay after restart | No host-process adoption, live cross-worker migration, or arbitrary in-flight graph restart. Started executions never automatically rerun. | +| Model/PII/provider-text protection | Explicit SDK host-service adapter supports protected provider text; saved-agent model/PII guard remains | Builder models, input/model callbacks and product policy wiring remain required before protected product rollout. | +| Stream circuit breakers and tool-policy hooks | Forwarded to the worker; hook failure stops execution | Domain tools must also authorize signed caller identity; trusted factories must retain the supplied adapters. | +| Agent-builder model, parameters, tools, capabilities | Name/instructions/identity are passed; worker owns the graph/model/tools | SDK `HostChatModel` and `createHostModelService` are available; remote model transport and builder wiring are still required to make settings authoritative. | +| Host MCP, web/code/browser tools, user tool credentials | Authorized root-agent schema tools execute through host RPC | Host credentials remain local; child-agent authorization and broader host-service parity remain separate integrations. | +| Uploaded files, generated artifacts, download authorization | Message data can cross the wire | Host file services, sandbox storage, and artifact authorization do not have remote adapters; attachment/file parity is not established. | +| Live steering and mid-stream preemption | Not integrated | A remote execution-control adapter and acceptance tests are required. | +| Foreground/nested/detached subagents | Worker may construct its own SDK graph | Native configured compositions are rejected; detached child checkpoint threads/context/usage sinks are not integrated. | +| Context pruning, compaction, summaries, cache/fading policy | Worker can use SDK features; terminal context metadata is returned | Host configuration and continuation policy are not automatically installed on the worker. Main-chat behavioral/performance parity is not established. | +| Token usage, cost/balance accounting | Native model events can be transported | Arbitrary worker model attribution and nested usage/balance enforcement need an explicit contract and tests; do not assume billing parity. | +| Tracing and tenant trace/export/redaction policy | Worker can configure SDK tracing itself | Host tracing callbacks and tenant export policy are not automatically inherited. Correlated, policy-safe tracing remains an integration gap. | +| Schedules/background/Responses callers | The bridge returns a Run through the common execution seam | Full lifecycle acceptance for these callers has not been performed. | +| Console Assistant and Schema Advisor | No product cutover in this change | Wire Schema Advisor, close its required gaps, then adopt shared chat components and compare performance. | Do not enable a workflow on the assumption that a native chat control is honored remotely. Its required rows must be implemented and verified first. Keep this matrix current as adapters land; @@ -221,3 +221,80 @@ Caller-owned function tools (`clientDelegatedToolNames`) are not host tools. Rem execution rejects that configuration until an explicit ownership/continuation adapter is available; their schemas must never be reinterpreted as permission to execute on the host. Native Responses execution without a remote SDK binding retains its existing behavior. + +## Host provider-text service + +Programmatic hosts can pass `hostServices.providerText` to `createRemoteSdkRun` from +`@librechat/api/sdk`. This is the exact binding returned by the SDK's +`createHostProviderTextService({ identity, policy, admission, inspectionTimeoutMs })`. +Create the binding from authenticated identity and a trusted host policy. Reuse a +`ProviderTextAdmission` object across all runs belonging to the host-selected quota +(typically a tenant/runtime), including reconnects. Configure its concurrency and +byte limits and the host inspection deadline explicitly; the transport does not +invent or reset those SDK-owned limits. This capability object contains callbacks +and is supplied by the host integration, not reconstructed from YAML or worker data. + +```js +const { ProviderTextAdmission, createHostProviderTextService } = require('@librechat/agents'); +const { createRemoteSdkRun } = require('@librechat/api/sdk'); + +// Retain with the host tenant/runtime registry, outside per-request code. +const admission = new ProviderTextAdmission({ + maxConcurrentInspections: 4, + maxBufferedBytes: 4 * 1024 * 1024, +}); + +const run = await createRemoteSdkRun({ + config, + identity, + remote, + hostServices: { + providerText: createHostProviderTextService({ + identity, + policy: trustedHostOutputPolicy, + admission, + inspectionTimeoutMs: 5000, + }), + }, +}); +``` + +Both sides require SDK 4.2.7 and the new bridge's `providerText: 1` capability. +Protected runs fail before factory admission on older workers. The worker receives +`config.providerTextProtection`; its factory must retain that exact policy on its +returned SDK graph. Omitting it fails before model execution. Custom graphs remain +trusted code and must install it on every applicable SDK Run. Main-chat's model/PII +rejection in saved-agent dispatch stays in place: this output-text adapter does not +supply input/model callbacks, authoritative builder model selection, host model +credentials, or policy for model calls made outside the SDK. SDK 4.2.7 also provides +`HostChatModel` and `createHostModelService` for host-owned model execution; those +contracts still need authenticated transport and saved-agent integration before +this guard can be removed. + +The worker buffers a complete model attempt through the same SDK release boundary +as local execution, then sends one `policy.providerText` RPC. Only canonical approved +text reaches the normal event handlers and terminal snapshot. Known policy failure +codes use the SDK's versioned, sanitized envelope. A cancelled or timed-out host +inspector keeps its SDK admission and memory charges until its underlying work +settles; observe `admission.snapshot()` for retained work and drain/terminate a hung +owner instead of replacing its quota. These quotas remain process-local. + +Candidate RPCs are encrypted before entering the existing bounded/recoverable +transport. Each host execution holds a volatile X25519 private key; each request +uses a fresh ephemeral X25519 key, HKDF-SHA256 and AES-256-GCM. Recovery logs contain +ciphertext and public keys, never the candidate plaintext or the host private key. +Authentication still comes from the signed execution binding and TLS; encryption +is not an authorization mechanism. The host drops its key reference at terminal +cleanup. Existing same-host/same-worker reconnect can replay the encrypted request +or canonical reply without rerunning inspection. Host-process adoption remains +unsupported, and ciphertext is still sensitive retained data subject to journal +TTL, deletion and access controls. This does not change the retention policy for +other event/checkpoint data already carried by the bridge. + +The existing `maxFrameBytes` and `maxBufferedBytes` bound encrypted frames as well. +Base64/envelope overhead reduces the maximum candidate fitting a frame; oversized +attempts fail closed, without plaintext fallback or unbounded chunking. Align +transport limits and SDK policy limits with the workload before enabling it. +Run the separate-process example benchmark with `SDK_BENCHMARK_PROTECTION=true` +to compare the same deterministic custom graph locally and remotely with a +pass-through inspection policy; this is a transport measurement, not PII validation. diff --git a/examples/sdk-runtime/README.md b/examples/sdk-runtime/README.md index e7a50dfb24..f817e5e9c2 100644 --- a/examples/sdk-runtime/README.md +++ b/examples/sdk-runtime/README.md @@ -130,3 +130,17 @@ Run `npm run test:cache-integration:sdk --workspace=@librechat/api` against loca fault-injection tests, and the Redis Playwright lane's `remote-sdk-recovery.spec.ts` for a real LibreChat custom-graph approval, wire outage, reconnection and saved-history test. Set `SDK_RUNTIME_RECOVERY=true` for `benchmark.cjs` to include Redis journal overhead. + +## Protected provider-text benchmark + +With SDK 4.2.7 and this bridge on both sides, run +`SDK_BENCHMARK_PROTECTION=true node examples/sdk-runtime/benchmark.cjs` against the +example worker. Add `SDK_RUNTIME_RECOVERY=true` to include Redis recovery. Both +local and remote executions use the same deterministic pass-through output policy; +the remote path adds host inspection through the SDK contract. This benchmark does +not implement a production PII detector or enable protected saved-agent chat. + +See [host provider-text services](../../docs/sdk/agents.md#host-provider-text-service) +for admission ownership, encrypted journal payloads, and the remaining model/input +policy guards. The existing factories retain `input.config`, including the new +provider-text protection adapter, for both the minimal and custom-graph examples. diff --git a/examples/sdk-runtime/agent.cjs b/examples/sdk-runtime/agent.cjs index c74ff48d6f..1dbaa302ce 100644 --- a/examples/sdk-runtime/agent.cjs +++ b/examples/sdk-runtime/agent.cjs @@ -4,6 +4,7 @@ const { Run, Providers } = require('@librechat/agents'); const { AIMessageChunk, HumanMessage } = require('@librechat/agents/langchain/messages'); const { tool } = require('@librechat/agents/langchain/tools'); const { FakeChatModel } = require('@langchain/core/utils/testing'); +const { ChatGenerationChunk } = require('@langchain/core/outputs'); const { Annotation, StateGraph, @@ -89,6 +90,15 @@ async function createExampleRun(input, { complex = true, stepDelayMs = 0 } = {}) }, ], }); + model._streamResponseChunks = async function* (messages) { + const { generations } = await this._generate(messages); + for (const generation of generations) { + yield new ChatGenerationChunk({ + ...generation, + text: typeof generation.message.content === 'string' ? generation.message.content : '', + }); + } + }; run.Graph.overrideModel = model; } if (complex) { diff --git a/examples/sdk-runtime/benchmark.cjs b/examples/sdk-runtime/benchmark.cjs index f77eb6eaf2..db028448a8 100644 --- a/examples/sdk-runtime/benchmark.cjs +++ b/examples/sdk-runtime/benchmark.cjs @@ -1,10 +1,34 @@ const { performance } = require('node:perf_hooks'); const { randomUUID } = require('node:crypto'); -const { GraphEvents, Providers } = require('@librechat/agents'); +const { + GraphEvents, + Providers, + ProviderTextAdmission, + createHostProviderTextService, +} = require('@librechat/agents'); const { HumanMessage } = require('@librechat/agents/langchain/messages'); const { createRemoteSdkRun } = require('@librechat/api/sdk'); const { createExampleRun } = require('./agent.cjs'); +const protectedOutput = process.env.SDK_BENCHMARK_PROTECTION === 'true'; +const admission = new ProviderTextAdmission({ + maxConcurrentInspections: 4, + maxBufferedBytes: 4194304, +}); +// A deterministic pass-through policy measures bridge cost, not production PII detection. +const policy = { + version: 1, + timeoutMs: 10000, + maxAttemptBytes: 1048576, + maxBufferedBytes: 4194304, + classify: () => 'prose', + inspect: ({ content }) => ({ + version: 1, + ok: true, + value: { content, replacements: 0, categories: [] }, + }), +}; + async function measure(remote) { const identity = { runtimeId: process.env.SDK_RUNTIME_ID || 'remote-example', @@ -17,6 +41,7 @@ async function measure(remote) { const started = performance.now(); const config = { runId: identity.runId, + ...(protectedOutput && { providerTextProtection: policy }), returnContent: true, tokenCounter: () => 1, customHandlers: { @@ -36,6 +61,16 @@ async function measure(remote) { ? await createRemoteSdkRun({ config, identity, + ...(protectedOutput && { + hostServices: { + providerText: createHostProviderTextService({ + identity, + policy, + admission, + inspectionTimeoutMs: 5000, + }), + }, + }), remote: { url: process.env.SDK_RUNTIME_URL || 'ws://127.0.0.1:8804/sdk', secret: process.env.SDK_RUNTIME_SECRET || '', @@ -74,6 +109,7 @@ async function main() { JSON.stringify( { mode: 'deterministic custom graph, five warm samples', + protectedOutput, local, remote, median: { diff --git a/package-lock.json b/package-lock.json index 08d663d053..211e5e2c3b 100644 --- a/package-lock.json +++ b/package-lock.json @@ -70,7 +70,7 @@ "@azure/storage-blob": "^12.30.0", "@google/genai": "^2.8.0", "@keyv/redis": "5.1.6", - "@librechat/agents": "^4.2.6", + "@librechat/agents": "^4.2.7", "@librechat/api": "*", "@librechat/data-schemas": "*", "@microsoft/microsoft-graph-client": "^3.0.7", @@ -9479,9 +9479,9 @@ } }, "node_modules/@librechat/agents": { - "version": "4.2.6", - "resolved": "https://registry.npmjs.org/@librechat/agents/-/agents-4.2.6.tgz", - "integrity": "sha512-UWp0UjIrXIt/tdO5BWDaTRpVQFN6yEHwmDdAregs1yHN/X/8GHu2D3ParQB0ze3NR3nm7Mkps/K0VB476oA7UQ==", + "version": "4.2.7", + "resolved": "https://registry.npmjs.org/@librechat/agents/-/agents-4.2.7.tgz", + "integrity": "sha512-j6TfPPZhiEHMFyT7xVc1y3Hh+w+l9YOkMf/0IlJU/GDoyH+DUyVElU9fjdmUVNSMcCHOQb0diHS7B9sQSofD8g==", "license": "MIT", "dependencies": { "@anthropic-ai/sdk": "^0.115.0", @@ -42444,7 +42444,7 @@ "@azure/identity": "^4.14.0", "@azure/storage-blob": "^12.30.0", "@keyv/redis": "5.1.6", - "@librechat/agents": "^4.2.6", + "@librechat/agents": "^4.2.7", "@librechat/data-schemas": "*", "@modelcontextprotocol/sdk": "^1.32.1", "@opentelemetry/api": "^1.9.0", diff --git a/packages/api/package.json b/packages/api/package.json index 88901f9612..a58eb18724 100644 --- a/packages/api/package.json +++ b/packages/api/package.json @@ -120,7 +120,7 @@ "@azure/identity": "^4.14.0", "@azure/storage-blob": "^12.30.0", "@keyv/redis": "5.1.6", - "@librechat/agents": "^4.2.6", + "@librechat/agents": "^4.2.7", "@librechat/data-schemas": "*", "@modelcontextprotocol/sdk": "^1.32.1", "@opentelemetry/api": "^1.9.0", diff --git a/packages/api/src/agents/remoteSdk/bridge.spec.ts b/packages/api/src/agents/remoteSdk/bridge.spec.ts index 191cd33e30..6544c56b75 100644 --- a/packages/api/src/agents/remoteSdk/bridge.spec.ts +++ b/packages/api/src/agents/remoteSdk/bridge.spec.ts @@ -6,6 +6,8 @@ import { tool } from '@librechat/agents/langchain/tools'; import { FakeChatModel as TestModel } from '@langchain/core/utils/testing'; import { HumanMessage, AIMessageChunk } from '@librechat/agents/langchain/messages'; import { + createHostProviderTextService, + ProviderTextAdmission, Run, Providers, GraphEvents, @@ -1114,3 +1116,128 @@ it('rejects an old host transport before constructing the worker graph', async ( await runtime.close(); } }); + +describe('remote host provider-text protection', () => { + const binding = () => + createHostProviderTextService({ + identity, + admission: new ProviderTextAdmission({ + maxConcurrentInspections: 2, + maxBufferedBytes: 16384, + }), + inspectionTimeoutMs: 1000, + policy: { + version: 1, + timeoutMs: 10000, + maxAttemptBytes: 8192, + maxBufferedBytes: 16384, + classify: () => 'prose', + inspect: ({ content }) => ({ + version: 1, + ok: true, + value: { + content: content.replaceAll('PRIVATE', '[redacted]'), + replacements: 1, + categories: [], + }, + }), + }, + }); + it('releases only host-approved output through real remote SDK handlers and final persistence', async () => { + const runtime = await fixture(async (input) => { + const run = await factory(input); + run.Graph!.overrideModel = new FakeChatModel({ responses: ['PRIVATE prose'], sleep: 1 }); + return run; + }); + const visible: string[] = []; + try { + const run = await createRemoteSdkRun({ + config: { + ...hostConfig(), + customHandlers: { + [GraphEvents.ON_MESSAGE_DELTA]: { + handle: async (_event, data) => { + visible.push(JSON.stringify(data)); + }, + }, + }, + }, + identity, + remote: runtime.remote, + hostServices: { providerText: binding() }, + }); + const content = await run.processStream({ messages: [new HumanMessage('go')] }, invocation()); + expect(JSON.stringify(content)).toContain('[redacted]'); + expect(JSON.stringify(content)).not.toContain('PRIVATE'); + expect(visible.join('')).toContain('[redacted]'); + expect(visible.join('')).not.toContain('PRIVATE'); + expect(JSON.stringify(run.getRunMessages())).not.toContain('PRIVATE'); + } finally { + await runtime.close(); + } + }); + it('fails before model execution when a trusted factory omits the supplied protection', async () => { + const runtime = await fixture((input) => + factory({ ...input, config: { ...input.config, providerTextProtection: undefined } }), + ); + try { + const run = await createRemoteSdkRun({ + config: hostConfig(), + identity, + remote: runtime.remote, + hostServices: { providerText: binding() }, + }); + await expect( + run.processStream({ messages: [new HumanMessage('go')] }, invocation()), + ).rejects.toThrow('SDK runtime execution failed'); + expect(run.getRunMessages()).toEqual([]); + } finally { + await runtime.close(); + } + }); +}); + +it('rejects a worker without protected-text capability before factory admission', async () => { + const server = new WebSocketServer({ port: 0, host: '127.0.0.1' }); + await new Promise((resolve) => server.once('listening', resolve)); + const methods: string[] = []; + server.on('connection', (socket) => + createSdkPeer(socket, { + maxFrameBytes: 65536, + maxBufferedBytes: 131072, + timeoutMs: 2000, + onClose: () => undefined, + onFrame: async () => undefined, + onCall: async (method) => { + methods.push(method); + return { transportVersion: 2, hostTools: 2 }; + }, + }), + ); + const providerText = createHostProviderTextService({ + identity, + policy: { + version: 1, + timeoutMs: 1000, + maxAttemptBytes: 4096, + maxBufferedBytes: 8192, + classify: () => 'prose', + inspect: () => ({ version: 1, ok: false, error: { code: 'blocked' } }), + }, + }); + try { + const run = await createRemoteSdkRun({ + config: hostConfig(), + identity, + remote: { url: `ws://127.0.0.1:${(server.address() as AddressInfo).port}`, secret }, + hostServices: { providerText }, + }); + await expect(run.processStream({ messages: [] }, invocation())).rejects.toThrow( + 'SDK runtime execution failed', + ); + expect(methods).toEqual(['capabilities']); + } finally { + for (const socket of server.clients) socket.terminate(); + await new Promise((resolve) => server.close(() => resolve())); + } +}); diff --git a/packages/api/src/agents/remoteSdk/client.ts b/packages/api/src/agents/remoteSdk/client.ts index 944466eb02..9cec472c2f 100644 --- a/packages/api/src/agents/remoteSdk/client.ts +++ b/packages/api/src/agents/remoteSdk/client.ts @@ -13,6 +13,7 @@ import { } from '@librechat/agents'; import type { RunConfig, RunInterruptResult, RunStep, RunStepClosedEvent } from '@librechat/agents'; import type { + RemoteSdkHostServices, RemoteSdkOptions, RemoteSdkSnapshot, RemoteSdkStart, @@ -26,6 +27,7 @@ import { connectRecoveringSdkSocket } from './recovery/client'; import { remoteSdkLimits, isRemoteSdkSecret } from './types'; import { createHostToolService } from './hostTools'; import { createSnapshotReceiver } from './snapshot'; +import { createHostPolicyChannel } from './policy'; import { createSdkPeer } from './peer'; /** Construct a real local Run whose execution is delegated to one operator-trusted runtime. */ @@ -34,15 +36,17 @@ export async function createRemoteSdkRun({ identity, remote, resumeState, + hostServices, }: { config: RunConfig; + hostServices?: RemoteSdkHostServices; identity: Readonly; remote: RemoteSdkOptions; resumeState?: RemoteSdkResumeState; }): ReturnType { if (config.clientDelegatedToolNames?.length) throw new Error('Remote SDK client-owned tools require a supported ownership adapter'); - if (config.providerTextProtection) + if (config.providerTextProtection && !hostServices?.providerText) throw new Error('Remote SDK provider protection requires a supported policy adapter'); identity = Object.freeze({ ...identity }); const limits = remoteSdkLimits(remote); @@ -208,6 +212,9 @@ export async function createRemoteSdkRun({ }) : await legacy(); const execution = new AbortController(); + const providerText = hostServices?.providerText + ? createHostPolicyChannel(hostServices.providerText, limits) + : undefined; const terminal = createSnapshotReceiver(limits.maxBufferedBytes); snapshot = undefined; let settled = false; @@ -261,6 +268,13 @@ export async function createRemoteSdkRun({ onCall: async (method, data, _timeoutMs, signal) => { if (execution.signal.aborted || options.signal?.aborted) throw new Error('SDK runtime execution stopped'); + if (method === 'policy.providerText') { + if (!providerText) throw new Error('Host provider policy is unavailable'); + return providerText.inspect( + data, + signal ? AbortSignal.any([execution.signal, signal]) : execution.signal, + ); + } if (method === 'tools') { if (!toolHandler || !descriptors.length) throw new Error('Host tools are unavailable'); hostToolInvoke ??= createHostToolService({ @@ -387,6 +401,7 @@ export async function createRemoteSdkRun({ 'agents' in config.graphConfig ? config.graphConfig.agents[0] : config.graphConfig; const start: RemoteSdkStart = { transportVersion: 2, + providerText: providerText?.descriptor, hostTools: descriptors.length ? descriptors : undefined, operation, input, @@ -425,9 +440,12 @@ export async function createRemoteSdkRun({ const capabilities = (await peer.call('capabilities', null)) as { transportVersion?: number; hostTools?: number; + providerText?: number; }; if (capabilities?.transportVersion !== 2) throw new Error('Worker transport capability unavailable'); + if (providerText && capabilities?.providerText !== 1) + throw new Error('Worker provider policy capability unavailable'); if (descriptors.length) { if (capabilities?.hostTools !== 2) throw new Error('Worker host tool capability unavailable'); @@ -441,6 +459,7 @@ export async function createRemoteSdkRun({ return snapshot.content?.filter((part) => part != null); } finally { execution.abort(); + providerText?.dispose(); // A failed/cancelled remote run may leave host cleanup running. Keep the host // execution enrolled until those handlers drain, even if the wire has closed. await Promise.allSettled([...hostInvocations]); diff --git a/packages/api/src/agents/remoteSdk/policy.spec.ts b/packages/api/src/agents/remoteSdk/policy.spec.ts new file mode 100644 index 0000000000..bf42b7dee0 --- /dev/null +++ b/packages/api/src/agents/remoteSdk/policy.spec.ts @@ -0,0 +1,240 @@ +import { randomUUID } from 'node:crypto'; +import { EventEmitter } from 'node:events'; +import { createHostProviderTextService, ProviderTextAdmission } from '@librechat/agents'; +import type { ProviderTextProtection } from '@librechat/agents'; +import type WebSocket from 'ws'; +import { createHostPolicyChannel, createWorkerProviderTextPolicy } from './policy'; +import { RecoverySocket, createMemoryRecoveryLog } from './recovery/socket'; +import { createPolicyReceiver, createPolicySender } from './sealed'; +import { remoteSdkLimits } from './types'; + +const identity = { runtimeId: 'runtime', agentId: 'agent', runId: 'run', userId: 'user' }; +const limits = remoteSdkLimits({ maxFrameBytes: 8192 }); +const request = { version: 1 as const, identity, content: 'PRIVATE candidate' }; +function fixture(overrides: Partial = {}) { + const admission = new ProviderTextAdmission({ + maxConcurrentInspections: 1, + maxBufferedBytes: 8192, + }); + const bound = createHostProviderTextService({ + identity, + admission, + inspectionTimeoutMs: 100, + policy: { + version: 1, + timeoutMs: 1000, + maxAttemptBytes: 8192, + maxBufferedBytes: 16384, + classify: () => 'prose', + inspect: () => ({ + version: 1, + ok: true, + value: { content: 'approved', replacements: 1, categories: [] }, + }), + ...overrides, + }, + }); + const host = createHostPolicyChannel(bound, limits); + const call = jest.fn(async (_method, data, _timeoutMs, signal) => host.inspect(data, signal)); + const worker = createWorkerProviderTextPolicy({ + descriptor: host.descriptor, + identity, + peer: { call }, + limits, + }); + const inspect = (content: string, signal = new AbortController().signal) => + worker.inspect({ + version: 1, + content, + target: { source: 'message', field: 'text', provenance: 'model' }, + signal, + }); + return { host, worker, call, admission, inspect }; +} + +it('seals raw requests before RPC and returns only approved text', async () => { + const f = fixture(); + try { + expect(await f.inspect(request.content)).toMatchObject({ + ok: true, + value: { content: 'approved' }, + }); + expect(f.call).toHaveBeenCalledTimes(1); + expect(f.call.mock.calls[0][0]).toBe('policy.providerText'); + expect(JSON.stringify(f.call.mock.calls)).not.toContain('PRIVATE'); + expect(f.admission.snapshot()).toMatchObject({ inspections: 0, bufferedBytes: 0 }); + } finally { + f.host.dispose(); + } +}); + +it('forwards cancellation and retains host admission until an ignoring inspector drains', async () => { + let release!: () => void; + const held = new Promise((resolve) => { + release = resolve; + }); + const f = fixture({ + inspect: async () => { + await held; + return { + version: 1, + ok: true, + value: { content: 'late PRIVATE', replacements: 0, categories: [] }, + }; + }, + }); + const controller = new AbortController(); + const result = Promise.resolve(f.inspect(request.content, controller.signal)).catch( + (error: Error) => error, + ); + try { + controller.abort(); + expect(await result).toMatchObject({ code: 'cancelled' }); + expect(f.call.mock.calls[0][3]).toBe(controller.signal); + expect(f.admission.snapshot().retainedInspections).toBe(1); + await expect(f.inspect(request.content)).rejects.toMatchObject({ code: 'overflow' }); + release(); + await new Promise((resolve) => setImmediate(resolve)); + expect(f.admission.snapshot().inspections).toBe(0); + } finally { + release(); + f.host.dispose(); + } +}); + +it('uses host deadlines without a worker cancellation and sanitizes inspector errors', async () => { + const f = fixture({ + inspect: () => { + throw new Error('PRIVATE credential'); + }, + }); + try { + await expect(f.inspect(request.content)).rejects.toMatchObject({ + code: 'unavailable', + message: 'Provider text protection: unavailable', + }); + } finally { + f.host.dispose(); + } + let release!: () => void; + const held = new Promise((resolve) => { + release = resolve; + }); + const timed = fixture({ + inspect: async () => { + await held; + return { version: 1, ok: false, error: { code: 'blocked' } }; + }, + }); + try { + await expect(timed.inspect(request.content)).rejects.toMatchObject({ code: 'timeout' }); + expect(timed.admission.snapshot().retainedInspections).toBe(1); + } finally { + release(); + timed.host.dispose(); + } +}); + +it('validates the authenticated identity after decryption, before policy inspection', async () => { + const inspect = jest.fn< + ReturnType, + Parameters + >(() => ({ version: 1, ok: false, error: { code: 'blocked' } })); + const f = fixture({ inspect }); + const seal = createPolicySender(f.host.descriptor.publicKey, limits.maxFrameBytes); + try { + expect( + await f.host.inspect( + seal(JSON.stringify({ ...request, identity: { ...identity, userId: 'foreign' } })), + ), + ).toEqual({ version: 1, ok: false, error: { code: 'incompatible' } }); + expect(inspect).not.toHaveBeenCalled(); + } finally { + f.host.dispose(); + } +}); + +it('rejects tampering, foreign run keys, malformed envelopes and disposed receivers', () => { + const receiver = createPolicyReceiver(1024); + const other = createPolicyReceiver(1024); + const seal = createPolicySender(receiver.publicKey, 1024); + const payload = seal(request.content); + expect(receiver.open(payload)).toBe(request.content); + expect(seal(request.content)).not.toEqual(payload); + expect(() => other.open(payload)).toThrow(); + for (const changed of [ + null, + {}, + { ...payload, version: 2 }, + { ...payload, tag: Buffer.alloc(16).toString('base64') }, + { ...payload, nonce: Buffer.alloc(12).toString('base64') }, + { ...payload, ciphertext: 'invalid' }, + { ...payload, publicKey: other.publicKey }, + ]) { + expect(() => receiver.open(changed)).toThrow(); + } + receiver.dispose(); + other.dispose(); + expect(() => receiver.open(payload)).toThrow(); +}); + +it('bounds payloads before encryption/decryption and handles a large candidate without a regex stack overflow', () => { + const receiver = createPolicyReceiver(4); + const seal = createPolicySender(receiver.publicKey, 4); + expect(() => seal('too large')).toThrow(); + const large = createPolicySender(receiver.publicKey, 262144)('x'.repeat(262144)); + expect(() => receiver.open(large)).toThrow(); + const largeReceiver = createPolicyReceiver(262144); + expect( + largeReceiver.open(createPolicySender(largeReceiver.publicKey, 262144)('x'.repeat(262144))), + ).toHaveLength(262144); + receiver.dispose(); + largeReceiver.dispose(); +}); + +it('replays encrypted inspection frames without putting raw candidates or private keys in the recovery log', async () => { + const receiver = createPolicyReceiver(8192); + const seal = createPolicySender(receiver.publicKey, 8192); + const log = createMemoryRecoveryLog(32768); + const socket = new RecoverySocket({ + log, + maxFrameBytes: 8192, + maxBufferedBytes: 32768, + onDisconnect: () => undefined, + onFailure: (error) => { + throw error; + }, + }); + const payload = seal(JSON.stringify(request)); + try { + socket.send( + JSON.stringify({ + type: 'call', + id: randomUUID(), + method: 'policy.providerText', + data: payload, + }), + ); + await socket.flush(); + const entries = await log.read(0); + expect(JSON.stringify(entries)).not.toContain(request.content); + expect(JSON.stringify(entries)).not.toContain('privateKey'); + const wire = Object.assign(new EventEmitter(), { + readyState: 1, + bufferedAmount: 0, + send: jest.fn(), + close: jest.fn(), + terminate: jest.fn(), + }); + socket.attach(wire as unknown as WebSocket, randomUUID(), 0); + await socket.flush(); + const published = String(wire.send.mock.calls[0][0]); + expect(published).not.toContain(request.content); + const replay = JSON.parse(published.slice(published.indexOf('\n') + 1)); + expect(JSON.parse(receiver.open(replay.data))).toEqual(request); + expect(replay.data).toEqual(payload); + } finally { + receiver.dispose(); + socket.terminate(); + } +}); diff --git a/packages/api/src/agents/remoteSdk/policy.ts b/packages/api/src/agents/remoteSdk/policy.ts new file mode 100644 index 0000000000..c6227d58a1 --- /dev/null +++ b/packages/api/src/agents/remoteSdk/policy.ts @@ -0,0 +1,93 @@ +import { z } from 'zod'; +import { + createHostProviderTextProtection, + serializeProviderTextProtectionError, + deserializeProviderTextProtectionError, + ProviderTextProtectionError, +} from '@librechat/agents'; +import type { HostProviderTextRequest } from '@librechat/agents'; +import type { RemoteSdkHostServices, RemoteSdkStart, RemoteSdkLimits } from './types'; +import type { SdkAgentIdentity } from './identity'; +import type { SdkRpc } from './peer'; +import { createPolicyReceiver, createPolicySender } from './sealed'; + +export const policyDescriptorSchema = z + .object({ + version: z.literal(1), + publicKey: z.string().length(60), + limits: z + .object({ + version: z.literal(1), + timeoutMs: z.number().int().positive().max(2_147_483_647), + maxAttemptBytes: z.number().int().positive().max(Number.MAX_SAFE_INTEGER), + maxBufferedBytes: z.number().int().positive().max(Number.MAX_SAFE_INTEGER), + }) + .strict(), + }) + .strict(); + +/** Only sanitized failures and approved canonical text enter the peer's reply/logging path. */ +export function createHostPolicyChannel( + providerText: NonNullable, + limits: RemoteSdkLimits, +) { + const receiver = createPolicyReceiver(limits.maxFrameBytes); + return { + descriptor: { + version: 1 as const, + publicKey: receiver.publicKey, + limits: providerText.descriptor, + }, + dispose: receiver.dispose, + inspect: async (data: unknown, signal?: AbortSignal) => { + try { + let request: HostProviderTextRequest; + try { + request = JSON.parse(receiver.open(data)) as HostProviderTextRequest; + } catch { + throw new ProviderTextProtectionError('incompatible'); + } + const content = await providerText.service.inspect(request, signal); + return { version: 1 as const, ok: true as const, content }; + } catch (error) { + return serializeProviderTextProtectionError(error); + } + }, + }; +} + +export function createWorkerProviderTextPolicy(options: { + descriptor: NonNullable; + identity: Readonly; + peer: { call: SdkRpc }; + limits: RemoteSdkLimits; +}) { + const descriptor = policyDescriptorSchema.parse(options.descriptor); + const seal = createPolicySender(descriptor.publicKey, options.limits.maxFrameBytes); + return createHostProviderTextProtection({ + identity: options.identity, + descriptor: descriptor.limits, + service: { + version: 1, + inspect: async (request, signal) => { + let payload: ReturnType; + try { + payload = seal(JSON.stringify(request)); + } catch { + throw new ProviderTextProtectionError('overflow'); + } + const result = await options.peer.call( + 'policy.providerText', + payload, + options.limits.maxRunMs, + signal, + ); + const success = z + .object({ version: z.literal(1), ok: z.literal(true), content: z.string() }) + .safeParse(result); + if (!success.success) throw deserializeProviderTextProtectionError(result); + return success.data.content; + }, + }, + }); +} diff --git a/packages/api/src/agents/remoteSdk/recovery/runtime.cache_integration.spec.ts b/packages/api/src/agents/remoteSdk/recovery/runtime.cache_integration.spec.ts index 4a81658f39..1498e900f5 100644 --- a/packages/api/src/agents/remoteSdk/recovery/runtime.cache_integration.spec.ts +++ b/packages/api/src/agents/remoteSdk/recovery/runtime.cache_integration.spec.ts @@ -6,6 +6,8 @@ import { setTimeout as delay } from 'node:timers/promises'; import { FakeChatModel as TestModel } from '@langchain/core/utils/testing'; import { HumanMessage, AIMessageChunk } from '@librechat/agents/langchain/messages'; import { + createHostProviderTextService, + ProviderTextAdmission, Run, Providers, FakeChatModel, @@ -104,6 +106,12 @@ async function fixture(makeRun = factory, ownerId?: string) { maxBatchFrames: 64, maxBatchBytes: 1048576, }); + const journalEntries: string[] = []; + const append = journal.append.bind(journal); + journal.append = (session, lease, id, payloads, terminal) => { + journalEntries.push(...payloads); + return append(session, lease, id, payloads, terminal); + }; const sessionScopes = new Map(); const read = journal.read.bind(journal); journal.read = (session, after, count) => { @@ -162,6 +170,7 @@ async function fixture(makeRun = factory, ownerId?: string) { return false; }, createRun, + journalEntries, errors, connections: () => connections, drop: () => { @@ -789,3 +798,61 @@ it('does not publish a session admitted concurrently with shutdown', async () => release(); await expect(admission).rejects.toThrow('closed'); }); + +it('recovers a policy reply after a wire outage without repeating inspection or journaling raw output', async () => { + const raw = 'PRIVATE-PROVIDER-CANDIDATE'; + const runtime = await fixture(async (input) => { + const run = await factory(input); + run.Graph!.overrideModel = new FakeChatModel({ responses: [raw], sleep: 1 }); + return run; + }); + const admission = new ProviderTextAdmission({ + maxConcurrentInspections: 1, + maxBufferedBytes: 16384, + }); + const inspect = jest.fn(async () => { + runtime.drop(); + await delay(50); + return { + version: 1 as const, + ok: true as const, + value: { content: 'approved prose', replacements: 1, categories: [] }, + }; + }); + const providerText = createHostProviderTextService({ + identity, + admission, + inspectionTimeoutMs: 2000, + policy: { + version: 1, + timeoutMs: 10000, + maxAttemptBytes: 8192, + maxBufferedBytes: 16384, + classify: () => 'prose', + inspect, + }, + }); + try { + const run = await createRemoteSdkRun({ + config: hostConfig(async () => undefined), + identity, + remote: runtime.remote, + hostServices: { providerText }, + }); + const content = await run.processStream( + { messages: [new HumanMessage('go')] }, + { version: 'v2', configurable: { thread_id: identity.conversationId } }, + ); + expect(JSON.stringify(content)).toContain('approved prose'); + expect(JSON.stringify(run.getRunMessages())).not.toContain(raw); + expect(runtime.connections()).toBeGreaterThan(1); + expect(runtime.createRun).toHaveBeenCalledTimes(1); + expect(inspect).toHaveBeenCalledTimes(1); + expect(runtime.journalEntries.join('')).toContain('policy.providerText'); + expect(runtime.journalEntries.join('')).not.toContain(raw); + expect(runtime.errors).toEqual([]); + expect(admission.snapshot().inspections).toBe(0); + } finally { + await runtime.close(); + } +}); diff --git a/packages/api/src/agents/remoteSdk/sealed.ts b/packages/api/src/agents/remoteSdk/sealed.ts new file mode 100644 index 0000000000..566b9684bd --- /dev/null +++ b/packages/api/src/agents/remoteSdk/sealed.ts @@ -0,0 +1,118 @@ +import { z } from 'zod'; +import { + createPublicKey, + generateKeyPairSync, + diffieHellman, + hkdfSync, + randomBytes, + createCipheriv, + createDecipheriv, +} from 'node:crypto'; +import type { KeyObject } from 'node:crypto'; + +const context = Buffer.from('librechat-sdk-provider-text/v1'); +const base64 = z.string().regex(/^[A-Za-z0-9+/]*={0,2}$/); +const publicKeySchema = base64.length(60); +const envelopeSchema = z + .object({ + version: z.literal(1), + publicKey: publicKeySchema, + nonce: base64.length(16), + tag: base64.length(24), + ciphertext: base64, + }) + .strict(); +type Envelope = z.infer; + +function publicKey(value: string): KeyObject { + const key = createPublicKey({ + key: Buffer.from(publicKeySchema.parse(value), 'base64'), + format: 'der', + type: 'spki', + }); + if (key.asymmetricKeyType !== 'x25519') throw new Error('Invalid SDK policy key'); + return key; +} + +function deriveKey(privateKey: KeyObject, peerKey: KeyObject, nonce: Buffer): Buffer { + const secret = diffieHellman({ privateKey, publicKey: peerKey }); + try { + return Buffer.from(hkdfSync('sha256', secret, nonce, context, 32)); + } finally { + secret.fill(0); + } +} + +/** Per-run private key stays on the host; recovery journals receive ciphertext and public keys only. */ +export function createPolicyReceiver(maxBytes: number): { + publicKey: string; + open(envelope: unknown): string; + dispose(): void; +} { + const pair = generateKeyPairSync('x25519'); + let privateKey: KeyObject | undefined = pair.privateKey; + return { + publicKey: pair.publicKey.export({ format: 'der', type: 'spki' }).toString('base64'), + open: (input) => { + if (!privateKey) throw new Error('SDK policy receiver closed'); + const envelope = envelopeSchema.parse(input); + if (envelope.ciphertext.length > Math.ceil(maxBytes / 3) * 4) + throw new Error('SDK policy payload exceeds limit'); + const nonce = Buffer.from(envelope.nonce, 'base64'); + const key = deriveKey(privateKey, publicKey(envelope.publicKey), nonce); + try { + const decipher = createDecipheriv('aes-256-gcm', key, nonce); + decipher.setAAD(context); + decipher.setAuthTag(Buffer.from(envelope.tag, 'base64')); + const ciphertext = Buffer.from(envelope.ciphertext, 'base64'); + if (ciphertext.length > maxBytes) throw new Error('SDK policy payload exceeds limit'); + const pending = decipher.update(ciphertext); + try { + const final = decipher.final(); + const plaintext = Buffer.concat([pending, final]); + try { + return plaintext.toString('utf8'); + } finally { + plaintext.fill(0); + final.fill(0); + } + } finally { + pending.fill(0); + } + } finally { + key.fill(0); + } + }, + dispose: () => { + privateKey = undefined; + }, + }; +} + +/** Encrypt before handing the candidate to a peer, queue, or replay log. */ +export function createPolicySender( + receiverKey: string, + maxBytes: number, +): (text: string) => Envelope { + const recipient = publicKey(receiverKey); + return (text) => { + if (Buffer.byteLength(text) > maxBytes) throw new Error('SDK policy payload exceeds limit'); + const pair = generateKeyPairSync('x25519'); + const nonce = randomBytes(12); + const key = deriveKey(pair.privateKey, recipient, nonce); + try { + const cipher = createCipheriv('aes-256-gcm', key, nonce); + cipher.setAAD(context); + const ciphertext = Buffer.concat([cipher.update(text, 'utf8'), cipher.final()]); + return { + version: 1, + publicKey: pair.publicKey.export({ format: 'der', type: 'spki' }).toString('base64'), + nonce: nonce.toString('base64'), + tag: cipher.getAuthTag().toString('base64'), + ciphertext: ciphertext.toString('base64'), + }; + } finally { + key.fill(0); + } + }; +} diff --git a/packages/api/src/agents/remoteSdk/server.ts b/packages/api/src/agents/remoteSdk/server.ts index 186605ec2c..fc32f32dff 100644 --- a/packages/api/src/agents/remoteSdk/server.ts +++ b/packages/api/src/agents/remoteSdk/server.ts @@ -15,6 +15,7 @@ import type { Server } from 'node:http'; import type { RemoteSdkFactoryInput, RemoteSdkLimits, RemoteSdkStart, SdkRun } from './types'; import type { RuntimeRecoveryOptions } from './recovery/server'; import type { SdkAgentIdentity } from './identity'; +import { policyDescriptorSchema, createWorkerProviderTextPolicy } from './policy'; import { createRuntimeRecovery, recoveryClaimSchema } from './recovery/server'; import { remoteSdkLimits, isRemoteSdkSecret } from './types'; import { RECOVERY_HEADER_BYTES } from './recovery/socket'; @@ -44,6 +45,7 @@ const claimSchema = z.object({ }); const startSchema = z.object({ transportVersion: z.literal(2), + providerText: policyDescriptorSchema.optional(), hostTools: z .array( z.object({ @@ -263,7 +265,8 @@ export function createRemoteSdkServer(options: RemoteSdkServerOptions): { throw new Error('Unexpected runtime frame'); }, onCall: async (method, data) => { - if (method === 'capabilities') return { transportVersion: 2, hostTools: 2 }; + if (method === 'capabilities') + return { transportVersion: 2, hostTools: 2, providerText: 1 }; if (method === 'tool.result') return workerTools.accept(data); if (method === 'tool.session') return workerTools.accept(data, 'session'); if (method !== 'run' || started) throw new Error('SDK execution already admitted'); @@ -336,6 +339,14 @@ export function createRemoteSdkServer(options: RemoteSdkServerOptions): { service: workerTools.service, }) : undefined; + const providerTextProtection = request.providerText + ? createWorkerProviderTextPolicy({ + descriptor: request.providerText, + identity, + peer, + limits, + }) + : undefined; const execute = async () => { await recovered?.begin(); const run = await options.createRun({ @@ -347,6 +358,7 @@ export function createRemoteSdkServer(options: RemoteSdkServerOptions): { hooks, humanInTheLoop: request.humanInTheLoop, streamLimits: request.streamLimits, + providerTextProtection, }, compileOptions: request.checkpoint ? { checkpointer: new RemoteSdkCheckpointer(peer.call) } @@ -360,6 +372,11 @@ export function createRemoteSdkServer(options: RemoteSdkServerOptions): { run.Graph?.defaultAgentId !== identity.agentId ) throw new Error('SDK runtime run identity mismatch'); + if ( + providerTextProtection && + run.Graph.providerTextProtection !== providerTextProtection + ) + throw new Error('SDK runtime omitted required provider protection'); if (hostTools) { const names = new Set( run.Graph.agentContexts diff --git a/packages/api/src/agents/remoteSdk/types.ts b/packages/api/src/agents/remoteSdk/types.ts index b7a81fd0da..3e807a780a 100644 --- a/packages/api/src/agents/remoteSdk/types.ts +++ b/packages/api/src/agents/remoteSdk/types.ts @@ -1,4 +1,6 @@ import type { + createHostProviderTextService, + HostProviderTextDescriptor, HostToolDescriptor, HostToolBindings, Run, @@ -51,8 +53,14 @@ export type SdkRun = Awaited>; export type SdkRunInput = Parameters[0]; export type SdkRunOptions = Parameters[1]; export type SdkEventData = Parameters[1]; +/** Explicit host-owned capabilities; never reconstructed from worker claims or YAML. */ +export interface RemoteSdkHostServices { + providerText?: ReturnType; +} + export interface RemoteSdkStart { transportVersion: 2; + providerText?: { version: 1; publicKey: string; limits: HostProviderTextDescriptor }; hostTools?: HostToolDescriptor[]; operation: 'start' | 'resume'; input: IState; @@ -89,7 +97,15 @@ export interface RemoteSdkFactoryInput { hostTools?: HostToolBindings; identity: Readonly; /** Host-owned event, hook, and checkpoint adapters. Retain these in the returned Run. */ - config: Pick; + config: Pick< + RunConfig, + | 'runId' + | 'customHandlers' + | 'hooks' + | 'humanInTheLoop' + | 'streamLimits' + | 'providerTextProtection' + >; compileOptions: NonNullable; signal: AbortSignal; agent: RemoteSdkStart['agent']; diff --git a/packages/api/src/sdk.ts b/packages/api/src/sdk.ts index 543b714b77..2c61d9433d 100644 --- a/packages/api/src/sdk.ts +++ b/packages/api/src/sdk.ts @@ -3,6 +3,7 @@ export { createRemoteSdkRun } from './agents/remoteSdk/client'; export type { RemoteSdkServerOptions } from './agents/remoteSdk/server'; export type { SdkAgentIdentity } from './agents/remoteSdk/identity'; export type { + RemoteSdkHostServices, RemoteSdkOptions, RemoteSdkResumeState, RemoteSdkFactoryInput,