From 056d44d95e80565a7e7ef819a5365636c4ad7172 Mon Sep 17 00:00:00 2001 From: Abhyudaya Baiju Tharakan Date: Fri, 9 Oct 2026 04:46:04 +0530 Subject: [PATCH] feat(mcp): add opt-in permission-aware deferred tool discovery Add multillm.tools.discover on both MCP endpoints behind DEFERRED_TOOLS_ENABLED (default off): grant-filtered local ranking with complete schemas, signed short-lived cursors, and grant and argument rechecks before every tool call. Grants live in the new tool_grants table (migration 0018) with compatibility rows for current tools. --- docs/deferred-tools.md | 39 ++ intelligence-migrations/0018_tool_grants.sql | 64 +++ package.json | 2 +- routes/gateway_mcp.py | 18 + routes/knowledge.py | 15 +- routes/knowledge_mcp.py | 41 +- services/deferred_tools.py | 256 ++++++++++++ tests/fixtures/secret_firewall_coverage.json | 1 + tests/test_deferred_tools.py | 400 +++++++++++++++++++ tests/test_deferred_tools_worker.mjs | 305 ++++++++++++++ worker/container-env.mjs | 1 + worker/control-state-d1.mjs | 9 + worker/d1-schema.mjs | 2 +- worker/knowledge-edge.mjs | 10 + worker/knowledge/deferred-tools.mjs | 336 ++++++++++++++++ worker/knowledge/skills-index.mjs | 11 + 16 files changed, 1503 insertions(+), 7 deletions(-) create mode 100644 docs/deferred-tools.md create mode 100644 intelligence-migrations/0018_tool_grants.sql create mode 100644 services/deferred_tools.py create mode 100644 tests/test_deferred_tools.py create mode 100644 tests/test_deferred_tools_worker.mjs create mode 100644 worker/knowledge/deferred-tools.mjs diff --git a/docs/deferred-tools.md b/docs/deferred-tools.md new file mode 100644 index 00000000..f036b2ab --- /dev/null +++ b/docs/deferred-tools.md @@ -0,0 +1,39 @@ +# Deferred tool discovery + +`DEFERRED_TOOLS_ENABLED=false` is the default. Empty values also disable it. Invalid values disable it and emit one warning containing only the setting name. While disabled, tool lists, calls, schemas, responses, headers and storage access follow the existing MCP behavior; `multillm.tools.discover` returns the existing method-not-found error. + +Enable the feature only after applying `0018_tool_grants.sql`. Flask reads grants through the fixed private `tool_grants` read operation on the existing model-state endpoint or an injected `app.extensions["deferred_tools"]` service. Worker uses `INTELLIGENCE_DB`. There is no fallback to local grants, public scopes alone or stale cached permissions. Missing storage or a missing table returns JSON HTTP 503 before execution. The private read also returns HTTP 503 when deferred tools are disabled in the Worker. + +## Explicit discovery + +Send a JSON-RPC request to the gateway MCP endpoint `/v1/mcp` or the Knowledge MCP endpoint `/mcp`: + +```json +{"jsonrpc":"2.0","id":1,"method":"multillm.tools.discover","params":{"query":"model search","limit":4}} +``` + +The result contains `tools`, each with its complete `inputSchema`, and `_meta.contract_digest` from the existing MCP contract digest implementation. `nextCursor`, when present, can be used with the same query and limit: + +```json +{"jsonrpc":"2.0","id":2,"method":"multillm.tools.discover","params":{"query":"model search","limit":4,"cursor":""}} +``` + +Queries must be nonempty, at most 500 characters, and contain no control characters. Limits are integers from 1 to 16; the default is 16. Unknown options are rejected. Ranking matches words in names, titles and descriptions locally, with deterministic ties by tool name. Permissions are filtered before ranking. A query without matches returns an empty tool list. No embedding, remote classification or provider call is made. + +A discovery response, including its JSON-RPC envelope, is bounded to 64 KiB. Pagination includes whole schemas only. A schema that cannot fit returns `tool_schema_too_large` (HTTP 413); it is never shortened or replaced. The existing canonical contract implementation also imposes its catalogue byte, node and depth limits. `tools/list` continues to return the entire authorized set, subject to the existing Knowledge toolset selector. Existing contract digest metadata and contract pins remain supported. + +## Grants and calls + +`tool_grants` stores principal ID, exact tool name, explicit scopes, allow/deny and row revision. The additive migration creates explicit compatibility rows for the current public tools and their existing required scopes. The `*` principal applies those rows to existing scope holders; it does not grant arbitrary tools or new scopes. An exact principal/tool row overrides its compatibility row, including a denial. New tools without a row are denied by default. Administrators must still have a grant; administrator scope does not bypass an explicit denial. Existing rows survive repeated migration execution. + +`tools/call` rereads grants and validates the full runtime schema, including when the tool was never advertised to the caller. Discovery does not grant permission or execute anything. Flask uses its existing JSON Schema validator. Worker preflight validates the static catalogue's `type`, `required`, `properties`, `additionalProperties`, string length and pattern, `enum`, numeric bounds, `items`, array length and uniqueness, `anyOf` and `oneOf` constraints. `default` and `description` are annotations and never change arguments. Unsupported or malformed schemas return `tool_validation_unavailable` (HTTP 503), including unsupported keywords in unused branches. Validation is bounded to depth 32, 8,192 schema and argument nodes, 262,144 string code units and 65,536 work steps; exceeding a bound also returns HTTP 503. Patterns are limited to 512 code units and come from the static catalogue. Existing operation-specific permission checks still apply, including provider options requiring management scope. Grant changes should increment the row revision and the existing `model_grants` control revision in the same transaction. + +With revision-aware configuration sync enabled, Flask binds cursors to its confirmed, fresh `model_grants` revision; unavailable or stale revision metadata returns HTTP 503. Worker reads the same control revision with the grant snapshot. With configuration sync disabled, each process or Worker isolate uses a stable random revision for its lifetime. Cursors also bind the observed grant rows, so revocations invalidate them even without configuration sync. + +Cursors are HMAC-signed and bind the authenticated principal and scopes, authorized tool contract digest, grant revision, observed grant rows, query, limit and page offset. Their maximum lifetime is 120 seconds from the first page; pagination does not renew it. A changed principal, scope, tool contract, toolset, grant or revision invalidates the cursor. Process restarts and movement to another isolate also invalidate it because signing keys stay only in memory. Start discovery again on `invalid_cursor` (HTTP 400). A concurrent grant change while preparing a page returns `tool_grants_changed` (HTTP 409). + +## Errors, cost and retention + +Denied calls return `tool_not_granted` (HTTP 403); invalid arguments return HTTP 400. Disabled discovery returns JSON-RPC `-32601`. Missing grant storage and missing validation collaborators return JSON HTTP 503. Errors do not expose rejected arguments, schema contents or storage exception text. Discovery never retries a tool call and does not change billing or provider retry rules. Explicit tool execution retains its existing cost and scope requirements. + +Only content-free grants and revisions are persisted. Queries and cursors are not stored by this feature and no prompt, response or query content is logged. Signing keys are generated internally and are never stored or returned. Storage reads are bounded to 4,096 applicable grant rows; malformed or oversized grant snapshots fail closed. diff --git a/intelligence-migrations/0018_tool_grants.sql b/intelligence-migrations/0018_tool_grants.sql new file mode 100644 index 00000000..2978df9a --- /dev/null +++ b/intelligence-migrations/0018_tool_grants.sql @@ -0,0 +1,64 @@ +-- Existing public contracts keep their explicit scope grants; unknown tools are denied. +CREATE TABLE IF NOT EXISTS tool_grants ( + principal_id TEXT NOT NULL CHECK(length(principal_id) BETWEEN 1 AND 128), + tool_name TEXT NOT NULL CHECK(length(tool_name) BETWEEN 1 AND 128), + scopes_json TEXT NOT NULL CHECK(json_valid(scopes_json) AND json_type(scopes_json) = 'array' AND json_array_length(scopes_json) > 0), + allowed INTEGER NOT NULL CHECK(allowed IN (0, 1)), + revision INTEGER NOT NULL CHECK(revision BETWEEN 0 AND 9007199254740991), + PRIMARY KEY (principal_id, tool_name) +); +CREATE INDEX IF NOT EXISTS tool_grants_tool ON tool_grants(tool_name, principal_id); + +-- Principal rows override these compatibility grants, including explicit denials. +INSERT OR IGNORE INTO tool_grants (principal_id, tool_name, scopes_json, allowed, revision) VALUES ('*', 'chat', '["chat"]', 1, 0); +INSERT OR IGNORE INTO tool_grants (principal_id, tool_name, scopes_json, allowed, revision) VALUES ('*', 'create_video', '["chat"]', 1, 0); +INSERT OR IGNORE INTO tool_grants (principal_id, tool_name, scopes_json, allowed, revision) VALUES ('*', 'generate_image', '["chat"]', 1, 0); +INSERT OR IGNORE INTO tool_grants (principal_id, tool_name, scopes_json, allowed, revision) VALUES ('*', 'generate_images_batch', '["chat"]', 1, 0); +INSERT OR IGNORE INTO tool_grants (principal_id, tool_name, scopes_json, allowed, revision) VALUES ('*', 'get_video', '["chat"]', 1, 0); +INSERT OR IGNORE INTO tool_grants (principal_id, tool_name, scopes_json, allowed, revision) VALUES ('*', 'knowledge_alexandria_execute', '["knowledge:read"]', 1, 0); +INSERT OR IGNORE INTO tool_grants (principal_id, tool_name, scopes_json, allowed, revision) VALUES ('*', 'knowledge_alexandria_inspect', '["knowledge:read"]', 1, 0); +INSERT OR IGNORE INTO tool_grants (principal_id, tool_name, scopes_json, allowed, revision) VALUES ('*', 'knowledge_alexandria_receipt', '["knowledge:read"]', 1, 0); +INSERT OR IGNORE INTO tool_grants (principal_id, tool_name, scopes_json, allowed, revision) VALUES ('*', 'knowledge_alexandria_search', '["knowledge:read"]', 1, 0); +INSERT OR IGNORE INTO tool_grants (principal_id, tool_name, scopes_json, allowed, revision) VALUES ('*', 'knowledge_artifact', '["knowledge:read"]', 1, 0); +INSERT OR IGNORE INTO tool_grants (principal_id, tool_name, scopes_json, allowed, revision) VALUES ('*', 'knowledge_context', '["knowledge:read"]', 1, 0); +INSERT OR IGNORE INTO tool_grants (principal_id, tool_name, scopes_json, allowed, revision) VALUES ('*', 'knowledge_context7_docs', '["knowledge:read"]', 1, 0); +INSERT OR IGNORE INTO tool_grants (principal_id, tool_name, scopes_json, allowed, revision) VALUES ('*', 'knowledge_context7_resolve_library', '["knowledge:read"]', 1, 0); +INSERT OR IGNORE INTO tool_grants (principal_id, tool_name, scopes_json, allowed, revision) VALUES ('*', 'knowledge_deepwiki_ask', '["knowledge:read"]', 1, 0); +INSERT OR IGNORE INTO tool_grants (principal_id, tool_name, scopes_json, allowed, revision) VALUES ('*', 'knowledge_deepwiki_contents', '["knowledge:read"]', 1, 0); +INSERT OR IGNORE INTO tool_grants (principal_id, tool_name, scopes_json, allowed, revision) VALUES ('*', 'knowledge_deepwiki_structure', '["knowledge:read"]', 1, 0); +INSERT OR IGNORE INTO tool_grants (principal_id, tool_name, scopes_json, allowed, revision) VALUES ('*', 'knowledge_exa_answer', '["knowledge:read"]', 1, 0); +INSERT OR IGNORE INTO tool_grants (principal_id, tool_name, scopes_json, allowed, revision) VALUES ('*', 'knowledge_exa_code_context', '["knowledge:read"]', 1, 0); +INSERT OR IGNORE INTO tool_grants (principal_id, tool_name, scopes_json, allowed, revision) VALUES ('*', 'knowledge_exa_contents', '["knowledge:read"]', 1, 0); +INSERT OR IGNORE INTO tool_grants (principal_id, tool_name, scopes_json, allowed, revision) VALUES ('*', 'knowledge_exa_search', '["knowledge:read"]', 1, 0); +INSERT OR IGNORE INTO tool_grants (principal_id, tool_name, scopes_json, allowed, revision) VALUES ('*', 'knowledge_firecrawl_crawl', '["knowledge:read"]', 1, 0); +INSERT OR IGNORE INTO tool_grants (principal_id, tool_name, scopes_json, allowed, revision) VALUES ('*', 'knowledge_firecrawl_crawl_status', '["knowledge:read"]', 1, 0); +INSERT OR IGNORE INTO tool_grants (principal_id, tool_name, scopes_json, allowed, revision) VALUES ('*', 'knowledge_firecrawl_extract', '["knowledge:read"]', 1, 0); +INSERT OR IGNORE INTO tool_grants (principal_id, tool_name, scopes_json, allowed, revision) VALUES ('*', 'knowledge_firecrawl_extract_status', '["knowledge:read"]', 1, 0); +INSERT OR IGNORE INTO tool_grants (principal_id, tool_name, scopes_json, allowed, revision) VALUES ('*', 'knowledge_firecrawl_map', '["knowledge:read"]', 1, 0); +INSERT OR IGNORE INTO tool_grants (principal_id, tool_name, scopes_json, allowed, revision) VALUES ('*', 'knowledge_firecrawl_scrape', '["knowledge:read"]', 1, 0); +INSERT OR IGNORE INTO tool_grants (principal_id, tool_name, scopes_json, allowed, revision) VALUES ('*', 'knowledge_firecrawl_search', '["knowledge:read"]', 1, 0); +INSERT OR IGNORE INTO tool_grants (principal_id, tool_name, scopes_json, allowed, revision) VALUES ('*', 'knowledge_handoff_delete', '["knowledge:read"]', 1, 0); +INSERT OR IGNORE INTO tool_grants (principal_id, tool_name, scopes_json, allowed, revision) VALUES ('*', 'knowledge_handoff_get', '["knowledge:read"]', 1, 0); +INSERT OR IGNORE INTO tool_grants (principal_id, tool_name, scopes_json, allowed, revision) VALUES ('*', 'knowledge_handoff_list', '["knowledge:read"]', 1, 0); +INSERT OR IGNORE INTO tool_grants (principal_id, tool_name, scopes_json, allowed, revision) VALUES ('*', 'knowledge_handoff_save', '["knowledge:read"]', 1, 0); +INSERT OR IGNORE INTO tool_grants (principal_id, tool_name, scopes_json, allowed, revision) VALUES ('*', 'knowledge_job_cancel', '["knowledge:manage"]', 1, 0); +INSERT OR IGNORE INTO tool_grants (principal_id, tool_name, scopes_json, allowed, revision) VALUES ('*', 'knowledge_memos_purge', '["knowledge:manage"]', 1, 0); +INSERT OR IGNORE INTO tool_grants (principal_id, tool_name, scopes_json, allowed, revision) VALUES ('*', 'knowledge_memos_stats', '["knowledge:manage"]', 1, 0); +INSERT OR IGNORE INTO tool_grants (principal_id, tool_name, scopes_json, allowed, revision) VALUES ('*', 'knowledge_mintlify_context', '["knowledge:read"]', 1, 0); +INSERT OR IGNORE INTO tool_grants (principal_id, tool_name, scopes_json, allowed, revision) VALUES ('*', 'knowledge_policy_update', '["knowledge:manage"]', 1, 0); +INSERT OR IGNORE INTO tool_grants (principal_id, tool_name, scopes_json, allowed, revision) VALUES ('*', 'knowledge_product_sites_get', '["knowledge:manage"]', 1, 0); +INSERT OR IGNORE INTO tool_grants (principal_id, tool_name, scopes_json, allowed, revision) VALUES ('*', 'knowledge_product_sites_update', '["knowledge:manage"]', 1, 0); +INSERT OR IGNORE INTO tool_grants (principal_id, tool_name, scopes_json, allowed, revision) VALUES ('*', 'knowledge_search', '["knowledge:read"]', 1, 0); +INSERT OR IGNORE INTO tool_grants (principal_id, tool_name, scopes_json, allowed, revision) VALUES ('*', 'knowledge_skills_discover', '["knowledge:read"]', 1, 0); +INSERT OR IGNORE INTO tool_grants (principal_id, tool_name, scopes_json, allowed, revision) VALUES ('*', 'knowledge_skills_find', '["knowledge:read"]', 1, 0); +INSERT OR IGNORE INTO tool_grants (principal_id, tool_name, scopes_json, allowed, revision) VALUES ('*', 'knowledge_skills_get', '["knowledge:read"]', 1, 0); +INSERT OR IGNORE INTO tool_grants (principal_id, tool_name, scopes_json, allowed, revision) VALUES ('*', 'knowledge_skills_import', '["knowledge:manage"]', 1, 0); +INSERT OR IGNORE INTO tool_grants (principal_id, tool_name, scopes_json, allowed, revision) VALUES ('*', 'knowledge_skills_preview', '["knowledge:read"]', 1, 0); +INSERT OR IGNORE INTO tool_grants (principal_id, tool_name, scopes_json, allowed, revision) VALUES ('*', 'knowledge_skills_report', '["knowledge:manage"]', 1, 0); +INSERT OR IGNORE INTO tool_grants (principal_id, tool_name, scopes_json, allowed, revision) VALUES ('*', 'knowledge_skills_sync', '["knowledge:manage"]', 1, 0); +INSERT OR IGNORE INTO tool_grants (principal_id, tool_name, scopes_json, allowed, revision) VALUES ('*', 'knowledge_source_refresh', '["knowledge:manage"]', 1, 0); +INSERT OR IGNORE INTO tool_grants (principal_id, tool_name, scopes_json, allowed, revision) VALUES ('*', 'knowledge_source_register', '["knowledge:manage"]', 1, 0); +INSERT OR IGNORE INTO tool_grants (principal_id, tool_name, scopes_json, allowed, revision) VALUES ('*', 'knowledge_source_update', '["knowledge:manage"]', 1, 0); +INSERT OR IGNORE INTO tool_grants (principal_id, tool_name, scopes_json, allowed, revision) VALUES ('*', 'knowledge_status', '["knowledge:manage"]', 1, 0); +INSERT OR IGNORE INTO tool_grants (principal_id, tool_name, scopes_json, allowed, revision) VALUES ('*', 'list_models', '["models"]', 1, 0); +INSERT OR IGNORE INTO tool_grants (principal_id, tool_name, scopes_json, allowed, revision) VALUES ('*', 'media_providers', '["chat"]', 1, 0); diff --git a/package.json b/package.json index 6cc36afa..d18ab3b5 100644 --- a/package.json +++ b/package.json @@ -9,7 +9,7 @@ "lint": "ruff check . --select E9,F63,F7,F82", "typecheck": "mypy --ignore-missing-imports --follow-imports=skip --disable-error-code import-untyped --disable-error-code var-annotated --disable-error-code arg-type --disable-error-code assignment --disable-error-code operator app.py routes services providers streaming", "test": "python -m pytest -q", - "test:worker": "node --test tests/test_cloudflare_worker.mjs tests/test_cascades_worker.mjs tests/test_cascades_dashboard.mjs tests/test_image_quality_worker.mjs tests/test_secret_scan_worker.mjs tests/test_secret_firewall_worker.mjs tests/test_secret_firewall_coverage_worker.mjs tests/test_roleplay_compaction_budget_worker.mjs tests/test_roleplay_compaction_model_worker.mjs tests/test_roleplay_stream_validation_worker.mjs tests/test_aihubmix_worker.mjs tests/test_gpt_image_moderation_worker.mjs tests/test_dashboard_scripts.mjs tests/test_operations_dashboard.mjs tests/test_opencode_reasoning_worker.mjs tests/test_opencode_thinking_worker.mjs tests/test_nanogpt_reasoning_worker.mjs tests/test_nanogpt_speed_routing_worker.mjs tests/test_sse_heartbeat_worker.mjs tests/test_roleplay_worker.mjs tests/test_roleplay_config_worker.mjs tests/test_roleplay_glm_failover_worker.mjs tests/test_roleplay_intelligence_worker.mjs tests/test_roleplay_memory_worker.mjs tests/test_roleplay_compatibility_worker.mjs tests/test_roleplay_history_reconciliation_worker.mjs tests/test_roleplay_output_contract_analysis.mjs tests/test_roleplay_output_contract_cleanup_worker.mjs tests/test_roleplay_output_contract_nonstream_worker.mjs tests/test_roleplay_output_contract_worker.mjs tests/test_roleplay_performance_worker.mjs tests/test_roleplay_quality_routing_worker.mjs tests/test_roleplay_reasoning_worker.mjs tests/test_roleplay_session_storage_worker.mjs tests/test_roleplay_transport_failure_worker.mjs tests/test_roleplay_unlimited_worker.mjs tests/test_roleplay_workbench_worker.mjs tests/test_roleplay_candidate_context_worker.mjs tests/test_roleplay_operator_worker.mjs tests/test_workbench_stream.mjs tests/test_intelligence_worker.mjs tests/test_intelligence_d1_worker.mjs tests/test_intelligence_auth_worker.mjs tests/test_intelligence_outbound_worker.mjs tests/test_intelligence_operator.mjs tests/test_control_users_worker.mjs tests/test_control_audit_worker.mjs tests/test_access_sso_worker.mjs tests/test_d1_schema_worker.mjs tests/test_shadow_eval_worker.mjs tests/test_auto_routes_worker.mjs tests/test_ai_outbound_worker.mjs tests/test_knowledge_*.mjs tests/test_control_state_worker.mjs tests/test_route_health_worker.mjs tests/test_gateway_mcp_worker.mjs tests/test_usage_ledger_worker.mjs tests/test_media_outbound_worker.mjs tests/test_media_files_worker.mjs tests/test_media_jobs_worker.mjs tests/test_tool_repair_worker.mjs tests/test_prometheus_worker.mjs tests/test_evaluation_noise_floor_worker.mjs tests/test_prompt_templates_worker.mjs tests/test_config_snapshots_worker.mjs tests/test_admission_leases_worker.mjs tests/test_edge_request_metrics_worker.mjs tests/test_request_cancellation_worker.mjs tests/test_mcp_contract_drift_worker.mjs tests/test_zero_content_retention_worker.mjs tests/test_prompt_cache_cost_worker.mjs tests/test_config_revision_sync_worker.mjs", + "test:worker": "node --test tests/test_cloudflare_worker.mjs tests/test_cascades_worker.mjs tests/test_cascades_dashboard.mjs tests/test_image_quality_worker.mjs tests/test_secret_scan_worker.mjs tests/test_secret_firewall_worker.mjs tests/test_secret_firewall_coverage_worker.mjs tests/test_roleplay_compaction_budget_worker.mjs tests/test_roleplay_compaction_model_worker.mjs tests/test_roleplay_stream_validation_worker.mjs tests/test_aihubmix_worker.mjs tests/test_gpt_image_moderation_worker.mjs tests/test_dashboard_scripts.mjs tests/test_operations_dashboard.mjs tests/test_opencode_reasoning_worker.mjs tests/test_opencode_thinking_worker.mjs tests/test_nanogpt_reasoning_worker.mjs tests/test_nanogpt_speed_routing_worker.mjs tests/test_sse_heartbeat_worker.mjs tests/test_roleplay_worker.mjs tests/test_roleplay_config_worker.mjs tests/test_roleplay_glm_failover_worker.mjs tests/test_roleplay_intelligence_worker.mjs tests/test_roleplay_memory_worker.mjs tests/test_roleplay_compatibility_worker.mjs tests/test_roleplay_history_reconciliation_worker.mjs tests/test_roleplay_output_contract_analysis.mjs tests/test_roleplay_output_contract_cleanup_worker.mjs tests/test_roleplay_output_contract_nonstream_worker.mjs tests/test_roleplay_output_contract_worker.mjs tests/test_roleplay_performance_worker.mjs tests/test_roleplay_quality_routing_worker.mjs tests/test_roleplay_reasoning_worker.mjs tests/test_roleplay_session_storage_worker.mjs tests/test_roleplay_transport_failure_worker.mjs tests/test_roleplay_unlimited_worker.mjs tests/test_roleplay_workbench_worker.mjs tests/test_roleplay_candidate_context_worker.mjs tests/test_roleplay_operator_worker.mjs tests/test_workbench_stream.mjs tests/test_intelligence_worker.mjs tests/test_intelligence_d1_worker.mjs tests/test_intelligence_auth_worker.mjs tests/test_intelligence_outbound_worker.mjs tests/test_intelligence_operator.mjs tests/test_control_users_worker.mjs tests/test_control_audit_worker.mjs tests/test_access_sso_worker.mjs tests/test_d1_schema_worker.mjs tests/test_shadow_eval_worker.mjs tests/test_auto_routes_worker.mjs tests/test_ai_outbound_worker.mjs tests/test_knowledge_*.mjs tests/test_control_state_worker.mjs tests/test_route_health_worker.mjs tests/test_gateway_mcp_worker.mjs tests/test_usage_ledger_worker.mjs tests/test_media_outbound_worker.mjs tests/test_media_files_worker.mjs tests/test_media_jobs_worker.mjs tests/test_tool_repair_worker.mjs tests/test_prometheus_worker.mjs tests/test_evaluation_noise_floor_worker.mjs tests/test_prompt_templates_worker.mjs tests/test_config_snapshots_worker.mjs tests/test_deferred_tools_worker.mjs tests/test_admission_leases_worker.mjs tests/test_edge_request_metrics_worker.mjs tests/test_request_cancellation_worker.mjs tests/test_mcp_contract_drift_worker.mjs tests/test_zero_content_retention_worker.mjs tests/test_prompt_cache_cost_worker.mjs tests/test_config_revision_sync_worker.mjs", "db:migrate": "python scripts/validate_sqlite_schema.py --apply", "db:validate": "python scripts/validate_sqlite_schema.py", "security:secrets": "python scripts/check_static_secrets.py", diff --git a/routes/gateway_mcp.py b/routes/gateway_mcp.py index 16d0af82..7e925b68 100644 --- a/routes/gateway_mcp.py +++ b/routes/gateway_mcp.py @@ -26,6 +26,8 @@ from routes.knowledge_management import permits from routes.knowledge_mcp import PROTOCOL_VERSIONS from services.client_headers import client_context_headers +from services import deferred_tools +from services.knowledge_client import KnowledgeError logger = logging.getLogger(__name__) @@ -661,6 +663,16 @@ def _mcp(): "serverInfo": SERVER_INFO, "instructions": INSTRUCTIONS}) if method == "ping": return _rpc_result(identifier, {}) + if deferred_tools.enabled() and method in {"tools/list", "multillm.tools.discover"}: + entries = [{"definition": definition, "scope": tool["scope"], "toolset": "gateway"} + for definition, tool in zip(tool_definitions(), TOOLS)] + try: + service = deferred_tools.runtime_service() + result = ({"tools": service.list_tools(entries, g.authenticated_user)} if method == "tools/list" + else service.discover(entries, g.authenticated_user, params)) + return _rpc_result(identifier, result) + except KnowledgeError as failure: + return _rpc_error(identifier, failure.code, failure.message, failure.status) if method == "tools/list": return _rpc_result(identifier, {"tools": [definition for definition, tool in zip(tool_definitions(), TOOLS) if _visible(tool)]}) @@ -676,6 +688,12 @@ def _mcp(): if not _visible(tool): return _rpc_result(identifier, _tool_error( "insufficient_scope", f"The key needs the {tool['scope']} scope for this tool.")) + if deferred_tools.enabled(): + try: + deferred_tools.runtime_service().authorize_call( + {"definition": tool, "scope": tool["scope"]}, g.authenticated_user, arguments) + except KnowledgeError as failure: + return _rpc_error(identifier, failure.code, failure.message, failure.status) result = call_tool(name, arguments) error = result.get("structuredContent", {}).get("error", {}) if error.get("code") == "secret_detected": diff --git a/routes/knowledge.py b/routes/knowledge.py index a9c5bfbb..01028a77 100644 --- a/routes/knowledge.py +++ b/routes/knowledge.py @@ -192,7 +192,8 @@ def _mcp_tool(identifier, params): "error": {"code": "insufficient_scope", "message": "The key is not authorized for this Knowledge tool."}, })}]}) try: - mcp.check_contract_pin(tool_name, request.headers.get("X-MultiLLM-MCP-Contract"), definition=entry["definition"]) + mcp.check_contract_pin(tool_name, request.headers.get("X-MultiLLM-MCP-Contract"), definition=entry["definition"], + user=g.authenticated_user, arguments=params.get("arguments", {})) except KnowledgeError as error: return _rpc_error(identifier, error.code, error.message, error.status) arguments = params.get("arguments", {}) @@ -255,13 +256,19 @@ def _mcp(): return _mcp_initialize(identifier, params) if method == "ping": return _rpc_result(identifier, {}) - if method == "tools/list": + if method == "tools/list" or method == "multillm.tools.discover" and mcp.deferred_tools.enabled(): try: toolsets = mcp.requested_toolsets(request.args.get("toolsets")) except ValueError: return _rpc_error(identifier, -32602, f"Unknown toolset. Use any of: {', '.join(mcp.TOOLSETS)}.") - return _rpc_result(identifier, mcp.discovery_for_user( - g.authenticated_user, toolsets, entries=_CATALOGUE["tools"])) + try: + if method == "multillm.tools.discover": + return _rpc_result(identifier, mcp.deferred_discovery( + g.authenticated_user, params, toolsets, entries=_CATALOGUE["tools"])) + return _rpc_result(identifier, mcp.discovery_for_user( + g.authenticated_user, toolsets, entries=_CATALOGUE["tools"])) + except KnowledgeError as error: + return _rpc_error(identifier, error.code, error.message, error.status) if method != "tools/call": return _rpc_error(identifier, -32601, "Method not found.") return _mcp_tool(identifier, params) diff --git a/routes/knowledge_mcp.py b/routes/knowledge_mcp.py index 5924a6c9..ec7e5a52 100644 --- a/routes/knowledge_mcp.py +++ b/routes/knowledge_mcp.py @@ -14,6 +14,10 @@ from routes import knowledge_skills as skills from services.knowledge_native import NATIVE_OPERATIONS, NATIVE_TOOLS from services import mcp_contract_drift as drift +from services import deferred_tools +from services.knowledge_client import KnowledgeError + +_UNSET = object() CATALOGUE_PATH = Path(__file__).resolve().parents[1] / "worker" / "knowledge-mcp-catalogue.json" # 2025-03-26 is not offered: it requires JSON-RPC batching, which this server does not accept. @@ -141,11 +145,25 @@ def discovery_contract(scopes, toolsets=None, *, enabled=None, entries=None): def discovery_for_user(user, toolsets=None, *, entries=None): scopes = ["admin"] if user.get("is_admin") else user.get("scopes") or [] + if deferred_tools.enabled(): + selected = catalogue()["tools"] if entries is None else entries + allowed = deferred_tools.runtime_service().list_tools(selected, user) + names = {tool["name"] for tool in allowed} + entries = [entry for entry in selected if entry["definition"]["name"] in names] return discovery_contract(scopes, toolsets, entries=entries) -def check_contract_pin(tool_name, pin, *, enabled=None, definition=None): +def check_contract_pin(tool_name, pin, *, enabled=None, definition=None, user=None, arguments=_UNSET): """Runtime preflight hook; invoke after tool authorization, before dispatch.""" + if deferred_tools.enabled(): + if user is None: + from flask import g + user = g.authenticated_user + if arguments is _UNSET: + entry = next(entry for entry in catalogue()["tools"] if entry["definition"]["name"] == tool_name) + deferred_tools.runtime_service().require_grant(entry, user) + raise KnowledgeError("tool_validation_unavailable", "The MCP dispatcher must supply the complete tool arguments.", 503) + authorize_deferred_call(user, tool_name, arguments) active = drift.digests_enabled() if enabled is None else enabled if not active or pin is None: return @@ -155,3 +173,24 @@ def check_contract_pin(tool_name, pin, *, enabled=None, definition=None): if definition is None: raise ValueError("Unknown Knowledge tool.") drift.check_contract_pin(definition, pin, enabled=True) + + +def deferred_discovery(user, params, toolsets=None, *, entries=None): + """Explicit discovery hook for the MCP dispatcher, including disabled method semantics.""" + if not deferred_tools.enabled(): + raise KnowledgeError(-32601, "Method not found.", 200) + selected = catalogue()["tools"] if entries is None else entries + if toolsets is not None: + selected = [entry for entry in selected if entry["toolset"] in toolsets] + return deferred_tools.runtime_service().discover(selected, user, params, digests=drift.digests_enabled()) + + +def authorize_deferred_call(user, tool_name, arguments, *, entries=None): + """Dispatcher preflight before contract pin checks and the existing operation parser.""" + if not deferred_tools.enabled(): + return + selected = catalogue()["tools"] if entries is None else entries + entry = next((entry for entry in selected if entry["definition"]["name"] == tool_name), None) + if entry is None: + raise KnowledgeError("unknown_tool", "Unknown Knowledge tool.", 400) + deferred_tools.runtime_service().authorize_call(entry, user, arguments) diff --git a/services/deferred_tools.py b/services/deferred_tools.py new file mode 100644 index 00000000..b8a2edaf --- /dev/null +++ b/services/deferred_tools.py @@ -0,0 +1,256 @@ +"""Permission-first, local tool discovery with complete schemas and short-lived cursors.""" +from __future__ import annotations + +import base64 +import binascii +import hashlib +import hmac +import json +import logging +import os +import re +import secrets +import time +from typing import Any + +from flask import current_app, has_app_context +from jsonschema import Draft202012Validator +from jsonschema.exceptions import SchemaError + +from services import config_revision_sync, control_state_d1, mcp_contract_drift as drift +from services.knowledge_client import KnowledgeError + +MAX_BYTES = 64 * 1024 +RPC_ENVELOPE_RESERVE = 4096 +MAX_LIMIT = 16 +CURSOR_TTL = 120 +MAX_GRANTS = 4096 +_PROCESS_REVISION = secrets.token_hex(16) +_warned = False +_default = None + + +def enabled(value=None): + global _warned + value = os.environ.get("DEFERRED_TOOLS_ENABLED", "") if value is None else value + if isinstance(value, bool): + return value + if isinstance(value, str): + flag = value.strip().lower() + if flag in {"", "0", "false", "off", "no"}: + return False + if flag in {"1", "true", "on", "yes"}: + return True + if not _warned: + logging.getLogger(__name__).warning("Invalid DEFERRED_TOOLS_ENABLED; deferred tools disabled") + _warned = True + return False + + +def unavailable(): + return KnowledgeError("tool_grants_unavailable", "The tool grant authority is unavailable. No tool was executed.", 503) + + +def grant_revision(): + """Use the confirmed security revision, never an old or unconfirmed copy.""" + if not config_revision_sync.load_settings().enabled: + return _PROCESS_REVISION + sync = current_app.extensions.get("config_revision_sync") if has_app_context() else None + if sync is None or not sync.settings.enabled: + raise unavailable() + state = sync.status()["domains"].get("model_grants") + if not state or state["stale"] or type(state["revision"]) is not int: + raise unavailable() + return state["revision"] + + +class D1GrantReader: + """Fixed private read through the existing model-state endpoint.""" + + def __call__(self, principal): + if not control_state_d1.using_d1(): + raise unavailable() + result = control_state_d1.call("model_overrides", "tool_grants", principal=principal) + if not isinstance(result, dict) or set(result) != {"version", "grants"} or type(result["version"]) is not int or result["version"] != 1: + raise unavailable() + return result["grants"] + + +def runtime_service(): + global _default + if has_app_context() and "deferred_tools" in current_app.extensions: + return current_app.extensions["deferred_tools"] + if _default is None: + _default = DeferredTools(D1GrantReader()) + return _default + + +def principal_for(user): + identity = user.get("id") or user.get("username") + scopes = user.get("scopes") or [] + if (not isinstance(identity, str) or not 0 < len(identity) <= 128 or identity == "*" + or not isinstance(scopes, list) or any(not isinstance(scope, str) for scope in scopes)): + raise KnowledgeError("invalid_principal", "The authenticated identity is unavailable.", 403) + return {"id": identity, "scopes": ["admin"] if user.get("is_admin") else scopes} + + +def parse_discovery(params): + if not isinstance(params, dict) or set(params) - {"query", "cursor", "limit"}: + raise KnowledgeError("invalid_request", "Discovery accepts query, cursor and limit only.", 400) + query, limit, cursor = params.get("query"), params.get("limit", MAX_LIMIT), params.get("cursor") + if (not isinstance(query, str) or not query.strip() or len(query) > 500 + or any(ord(char) < 32 or ord(char) == 127 or 0xD800 <= ord(char) <= 0xDFFF for char in query) + or type(limit) is not int or not 1 <= limit <= MAX_LIMIT + or cursor is not None and (not isinstance(cursor, str) or not 0 < len(cursor) <= 4096)): + raise KnowledgeError("invalid_request", "Use a query up to 500 characters, limit 1–16 and a valid cursor.", 400) + return query.strip().lower(), limit, cursor + + +def _json(value): + return json.dumps(value, sort_keys=True, separators=(",", ":"), ensure_ascii=True, allow_nan=False) + + +def _hash(value): + return hashlib.sha256(_json(value).encode()).hexdigest() + + +def _words(text): + return set(re.findall(r"[^\W_]+", text.lower(), flags=re.UNICODE)) + + +def rank_tools(definitions, query): + tokens = _words(query) + scored = [] + for tool in definitions: + score = sum(weight * len(tokens & _words(tool.get(field, ""))) + for field, weight in (("name", 3), ("title", 2), ("description", 1))) + if score: + scored.append((score, tool)) + return [tool for _, tool in sorted(scored, key=lambda item: (-item[0], item[1]["name"]))] + + +def _validated_grants(rows, identity): + if not isinstance(rows, list) or len(rows) > MAX_GRANTS: + raise unavailable() + grants = {} + for row in rows: + if (not isinstance(row, dict) or row.get("principal_id") not in {"*", identity} + or not isinstance(row.get("tool_name"), str) or not 0 < len(row["tool_name"]) <= 128 + or type(row.get("allowed")) is not int or row["allowed"] not in (0, 1) + or type(row.get("revision")) is not int or not 0 <= row["revision"] <= 9007199254740991 + or not isinstance(row.get("scopes"), list) or not row["scopes"] + or any(not isinstance(scope, str) or not 0 < len(scope) <= 80 for scope in row["scopes"])): + raise unavailable() + key = (row["principal_id"], row["tool_name"]) + if key in grants: + raise unavailable() + grants[key] = row + return grants + + +def _permitted(entry, principal, grants): + scopes = principal["scopes"] + if "admin" not in scopes and entry["scope"] not in scopes: + return False + name = entry["definition"]["name"] + row = grants.get((principal["id"], name), grants.get(("*", name))) + return bool(row and row["allowed"] and ("admin" in scopes or all(scope in scopes for scope in row["scopes"]))) + + +class DeferredTools: + """Read grants for every operation; discovery never creates or caches permissions.""" + + def __init__(self, read_grants, *, revision=grant_revision, clock=time.time, secret=None): + self.read_grants, self.revision, self.clock = read_grants, revision, clock + self._secret = secret if secret is not None else secrets.token_bytes(32) + + def _snapshot(self, principal): + try: + rows = self.read_grants(principal["id"]) + grants = _validated_grants(rows, principal["id"]) + revision = self.revision() + if not isinstance(revision, (str, int)) or isinstance(revision, bool): + raise unavailable() + stamp = _hash([grants[key] for key in sorted(grants)]) + return grants, revision, stamp + except KnowledgeError: + raise + except Exception: + raise unavailable() from None + + def list_tools(self, entries, user): + principal = principal_for(user) + grants, _, _ = self._snapshot(principal) + return [entry["definition"] for entry in entries if _permitted(entry, principal, grants)] + + def require_grant(self, entry, user): + principal = principal_for(user) + grants, _, _ = self._snapshot(principal) + if not _permitted(entry, principal, grants): + raise KnowledgeError("tool_not_granted", "The key is not granted permission for this tool.", 403) + + def authorize_call(self, entry, user, arguments): + self.require_grant(entry, user) + try: + schema = entry["definition"]["inputSchema"] + Draft202012Validator.check_schema(schema) + valid = isinstance(arguments, dict) and Draft202012Validator(schema).is_valid(arguments) + except (SchemaError, RecursionError, ValueError): + raise KnowledgeError("tool_validation_unavailable", "The runtime tool schema is unavailable.", 503) from None + if not valid: + raise KnowledgeError("invalid_arguments", "The arguments do not match the complete runtime tool schema.", 400) + self.require_grant(entry, user) + + def _sign(self, payload): + raw = _json(payload).encode() + encoded = base64.urlsafe_b64encode(raw).decode().rstrip("=") + signature = hmac.new(self._secret, encoded.encode(), hashlib.sha256).hexdigest() + return encoded + "." + signature + + def _decode(self, cursor, binding, count): + try: + encoded, signature = cursor.split(".") + expected = hmac.new(self._secret, encoded.encode(), hashlib.sha256).hexdigest() + if not hmac.compare_digest(expected, signature): + raise ValueError() + raw = base64.b64decode(encoded + "=" * (-len(encoded) % 4), altchars=b"-_", validate=True) + payload = json.loads(raw) + if (not isinstance(payload, dict) or set(payload) != set(binding) | {"o", "exp"} + or any(payload.get(key) != value for key, value in binding.items()) + or type(payload["o"]) is not int or not 0 < payload["o"] < count + or type(payload["exp"]) not in (int, float) or not self.clock() < payload["exp"] <= self.clock() + CURSOR_TTL): + raise ValueError() + return payload["o"], payload["exp"] + except (ValueError, TypeError, KeyError, binascii.Error, UnicodeDecodeError): + raise KnowledgeError("invalid_cursor", "The discovery cursor expired or its permissions or contract changed.", 400) from None + + def discover(self, entries, user, params, *, digests=False): + query, limit, cursor = parse_discovery(params) + principal = principal_for(user) + grants, revision, stamp = self._snapshot(principal) + tools = [entry["definition"] for entry in entries if _permitted(entry, principal, grants)] + try: + digest = drift.catalogue_digest(tools) + except ValueError: + raise KnowledgeError("tool_schema_too_large", "The authorized tool catalogue exceeds contract digest limits.", 413) from None + if digests: + tools = [{**tool, "_meta": {**tool.get("_meta", {}), "contract_digest": drift.contract_digest(tool)}} for tool in tools] + ranked = rank_tools(tools, query) + binding = {"v": 1, "p": _hash(principal), "d": digest, "r": revision, "g": stamp, "q": _hash(query), "l": limit} + offset, expires = self._decode(cursor, binding, len(ranked)) if cursor else (0, self.clock() + CURSOR_TTL) + page: dict[str, Any] = {"tools": [], "_meta": {"contract_digest": digest}} + stop = min(len(ranked), offset + limit) + for end in range(offset + 1, stop + 1): + candidate = {"tools": ranked[offset:end], "_meta": page["_meta"]} + if end < len(ranked): + candidate["nextCursor"] = self._sign({**binding, "o": end, "exp": expires}) + # Reserve the envelope, including a maximally escaped 200-character request ID. + if len(json.dumps(candidate, ensure_ascii=True).encode()) + RPC_ENVELOPE_RESERVE > MAX_BYTES: + if not page["tools"]: + raise KnowledgeError("tool_schema_too_large", "A complete tool schema cannot fit in a discovery response.", 413) + break + page = candidate + _, latest_revision, latest_stamp = self._snapshot(principal) + if (revision, stamp) != (latest_revision, latest_stamp): + raise KnowledgeError("tool_grants_changed", "Tool grants changed during discovery. Start discovery again.", 409) + return page diff --git a/tests/fixtures/secret_firewall_coverage.json b/tests/fixtures/secret_firewall_coverage.json index 7d3b6115..4f710401 100644 --- a/tests/fixtures/secret_firewall_coverage.json +++ b/tests/fixtures/secret_firewall_coverage.json @@ -252,6 +252,7 @@ "worker/knowledge/contracts.mjs", "worker/knowledge/corpus.mjs", "worker/knowledge/credentials.mjs", + "worker/knowledge/deferred-tools.mjs", "worker/knowledge/evidence.mjs", "worker/knowledge/handoff-contracts.mjs", "worker/knowledge/handoff-store.mjs", diff --git a/tests/test_deferred_tools.py b/tests/test_deferred_tools.py new file mode 100644 index 00000000..d36b5d08 --- /dev/null +++ b/tests/test_deferred_tools.py @@ -0,0 +1,400 @@ +"""Deferred discovery uses synthetic identities, grants, clocks and dispatch.""" +import copy +import json +import sqlite3 +from pathlib import Path +from unittest.mock import Mock + +import pytest +from flask import Flask, g + +from services import deferred_tools as deferred +from services import mcp_contract_drift as drift +from services.knowledge_client import KnowledgeError +from routes import gateway_mcp, knowledge_mcp + +USER = {"id": "reader", "scopes": ["models", "chat", "knowledge:read"]} + + +def entry(name, scope="models", description="model search", schema=None): + return {"scope": scope, "toolset": "core", "definition": { + "name": name, "description": description, "inputSchema": schema or { + "type": "object", "additionalProperties": False, "properties": {}}}} + + +def grant(name, scope="models", allowed=1, principal="*"): + return {"principal_id": principal, "tool_name": name, "scopes": [scope], "allowed": allowed, "revision": 1} + + +@pytest.fixture +def fixture(): + rows = [grant("models_a"), grant("models_b")] + revision = [1] + clock = [100] + store = Mock(side_effect=lambda principal: copy.deepcopy(rows)) + service = deferred.DeferredTools(store, revision=lambda: revision[0], clock=lambda: clock[0]) + return service, rows, revision, clock, store + + +def test_filter_before_ranking_and_full_authorized_list(fixture): + service, rows, *_ = fixture + entries = [entry("models_a"), entry("models_b"), entry("denied", description="secret exact match")] + assert service.discover(entries, USER, {"query": "secret exact match"})["tools"] == [] + assert [t["name"] for t in service.list_tools(entries, USER)] == ["models_a", "models_b"] + rows.append(grant("models_a", allowed=0, principal="reader")) + assert [t["name"] for t in service.list_tools(entries, USER)] == ["models_b"] + assert service.list_tools(entries, {"id": "reader", "scopes": []}) == [] + assert service.list_tools(entries, {"id": "reader", "scopes": ["admin"]}) == [entries[1]["definition"]] + + +def test_unadvertised_granted_call_and_runtime_validation(fixture): + service, rows, *_ = fixture + tool = entry("models_a") + service.authorize_call(tool, USER, {}) + with pytest.raises(KnowledgeError, match="arguments") as caught: + service.authorize_call(tool, USER, {"extra": True}) + assert caught.value.code == "invalid_arguments" + rows.append(grant("models_a", allowed=0, principal="reader")) + with pytest.raises(KnowledgeError) as caught: + service.authorize_call(tool, USER, {}) + assert caught.value.code == "tool_not_granted" and caught.value.status == 403 + + +def test_complete_schema_budget_and_pagination(fixture): + service, rows, *_ = fixture + entries = [entry(f"models_{i}", schema={"type": "object", "description": "é" * 1000}) for i in range(20)] + rows[:] = [grant(e["definition"]["name"]) for e in entries] + first = service.discover(entries, USER, {"query": "model", "limit": 16}) + assert len(first["tools"]) < 16 + assert len(json.dumps(first).encode()) <= 65536 + assert first["tools"][0]["inputSchema"] == entries[0]["definition"]["inputSchema"] + seen = [t["name"] for t in first["tools"]] + cursor = first["nextCursor"] + while cursor: + page = service.discover(entries, USER, {"query": "model", "limit": 16, "cursor": cursor}) + seen += [t["name"] for t in page["tools"]] + cursor = page.get("nextCursor") + assert len(seen) == len(set(seen)) == 20 + entries[0]["definition"]["inputSchema"]["description"] = "x" * 66000 + with pytest.raises(KnowledgeError) as caught: + service.discover(entries[:1], USER, {"query": "model"}) + assert caught.value.code == "tool_schema_too_large" + + +@pytest.mark.parametrize("change", ["tamper", "expiry", "principal", "query", "limit", "revision", "grants", "digest"]) +def test_cursor_bindings(fixture, change): + service, rows, revision, clock, _ = fixture + entries = [entry("models_a"), entry("models_b")] + args = {"query": "model", "limit": 1} + cursor = service.discover(entries, USER, args)["nextCursor"] + user = USER + if change == "tamper": + cursor = ("A" if cursor[0] != "A" else "B") + cursor[1:] + elif change == "expiry": + clock[0] += 120 + elif change == "principal": + user = {**USER, "id": "other"} + elif change == "query": + args["query"] = "search" + elif change == "limit": + args["limit"] = 2 + elif change == "revision": + revision[0] += 1 + elif change == "grants": + rows[0]["revision"] += 1 + else: + entries[0]["definition"]["inputSchema"]["properties"]["new"] = {"type": "string"} + with pytest.raises(KnowledgeError) as caught: + service.discover(entries, user, {**args, "cursor": cursor}) + assert caught.value.code == "invalid_cursor" + + +@pytest.mark.parametrize("params", [{}, {"query": ""}, {"query": "x", "limit": 17}, {"query": "x", "limit": True}, + {"query": "x", "paid_embedding": True}, {"query": "x", "cursor": "x" * 4097}]) +def test_input_bounds_before_storage(fixture, params): + service, *_, store = fixture + with pytest.raises(KnowledgeError): + service.discover([], USER, params) + store.assert_not_called() + + +@pytest.fixture +def gateway(monkeypatch, fixture): + monkeypatch.setenv("DEFERRED_TOOLS_ENABLED", "false") + app = Flask(__name__) + app.config.update(TESTING=True) + service, rows, *_ = fixture + rows[:] = [grant("list_models"), grant("chat", "chat")] + app.extensions["deferred_tools"] = service + monkeypatch.setattr(gateway_mcp, "api_authenticate_only", lambda **kwargs: lambda fn: fn) + gateway_mcp.register_gateway_mcp_routes(app, Mock(exempt=lambda fn: fn)) + @app.before_request + def identity(): + g.authenticated_user = copy.deepcopy(USER) + dispatch = Mock(return_value={"isError": False, "content": []}) + monkeypatch.setitem(gateway_mcp._HANDLERS, "list_models", dispatch) + return app, rows, dispatch + + +def rpc(app, method, params=None): + return app.test_client().post("/v1/mcp", json={"jsonrpc": "2.0", "id": 7, "method": method, "params": params or {}}) + + +@pytest.mark.parametrize("flag", ["", "false", "0", "malformed"]) +def test_registered_off_keeps_bytes_and_does_not_read_storage(gateway, monkeypatch, flag): + app, _, dispatch = gateway + expected = rpc(app, "tools/list") + monkeypatch.setenv("DEFERRED_TOOLS_ENABLED", flag) + app.extensions["deferred_tools"] = Mock(side_effect=AssertionError("storage while off")) + actual = rpc(app, "tools/list") + assert actual.data == expected.data and list(actual.headers) == list(expected.headers) + assert rpc(app, "multillm.tools.discover", {"query": "models"}).json["error"]["code"] == -32601 + assert rpc(app, "tools/call", {"name": "list_models", "arguments": {}}).json["result"]["isError"] is False + dispatch.assert_called_once() + + +def test_registered_discovery_calls_recheck_and_schema(gateway, monkeypatch): + app, rows, dispatch = gateway + monkeypatch.setenv("DEFERRED_TOOLS_ENABLED", "true") + assert [t["name"] for t in rpc(app, "tools/list").json["result"]["tools"]] == ["list_models", "chat"] + discovery = rpc(app, "multillm.tools.discover", {"query": "model"}).json["result"] + assert discovery["tools"] and discovery["_meta"]["contract_digest"] == drift.catalogue_digest( + [t for t in gateway_mcp.tool_definitions() if t["name"] in {"list_models", "chat"}]) + assert rpc(app, "tools/call", {"name": "list_models"}).json["result"]["isError"] is False + assert rpc(app, "tools/call", {"name": "list_models", "arguments": {"limit": 501}}).status_code == 400 + rows.append(grant("list_models", allowed=0, principal="reader")) + assert rpc(app, "tools/call", {"name": "list_models"}).status_code == 403 + dispatch.assert_called_once() + + +def test_registered_missing_table_fails_closed(gateway, monkeypatch): + app, _, dispatch = gateway + monkeypatch.setenv("DEFERRED_TOOLS_ENABLED", "true") + app.extensions["deferred_tools"] = deferred.DeferredTools(Mock(side_effect=sqlite3.OperationalError("no such table"))) + for method, params in [("tools/list", {}), ("multillm.tools.discover", {"query": "models"}), + ("tools/call", {"name": "list_models"})]: + response = rpc(app, method, params) + assert response.status_code == 503 and response.json["error"]["code"] == "tool_grants_unavailable" + dispatch.assert_not_called() + + +def test_knowledge_hooks_preserve_digests_and_full_schema(fixture, monkeypatch): + service, rows, *_ = fixture + app = Flask(__name__) + app.extensions["deferred_tools"] = service + rows[:] = [grant("knowledge_context", "knowledge:read")] + monkeypatch.setenv("DEFERRED_TOOLS_ENABLED", "true") + monkeypatch.setenv("MCP_CONTRACT_DIGESTS_ENABLED", "true") + with app.app_context(): + result = knowledge_mcp.discovery_for_user(USER) + assert [t["name"] for t in result["tools"]] == ["knowledge_context"] + assert "contract_digest" in result["tools"][0]["_meta"] + found = knowledge_mcp.deferred_discovery(USER, {"query": "technical"}) + assert found["tools"][0]["inputSchema"] == knowledge_mcp.QUERY_SCHEMA + definition = found["tools"][0] + knowledge_mcp.authorize_deferred_call(USER, definition["name"], {"query": "limits"}) + with pytest.raises(KnowledgeError): + knowledge_mcp.authorize_deferred_call(USER, definition["name"], {"query": "limits", "unexpected": 1}) + + +def test_revision_sync_uses_confirmed_model_grants_and_fails_stale(monkeypatch): + from services import config_revision_sync as revisions + app = Flask(__name__) + monkeypatch.setenv("CONFIG_REVISION_SYNC_ENABLED", "true") + sync = revisions.RevisionSync(revisions.SyncSettings(True), clock=lambda: 0) + sync.register("model_grants", lambda revision: None, security=True) + sync._domains["model_grants"].revision = 7 + sync._domains["model_grants"].checked = 0 + app.extensions["config_revision_sync"] = sync + with app.app_context(): + assert deferred.grant_revision() == 7 + sync._domains["model_grants"].checked = None + with pytest.raises(KnowledgeError): + deferred.grant_revision() + monkeypatch.setenv("CONFIG_REVISION_SYNC_ENABLED", "false") + assert deferred.grant_revision() == deferred.grant_revision() + + +def test_additive_migration_preserves_old_rows_and_denies_new_tools(): + db = sqlite3.connect(":memory:") + db.execute("CREATE TABLE control_revisions(domain TEXT PRIMARY KEY, revision INTEGER, updated_at TEXT)") + db.execute("INSERT INTO control_revisions VALUES('model_grants',7,'old')") + sql = (Path(__file__).resolve().parents[1] / "intelligence-migrations/0018_tool_grants.sql").read_text() + db.executescript(sql) + db.execute("INSERT INTO tool_grants VALUES(?,?,?,?,?)", ("reader", "custom", json.dumps(["models"]), 0, 9)) + db.executescript(sql) + assert db.execute("SELECT revision FROM control_revisions WHERE domain='model_grants'").fetchone() == (7,) + assert db.execute("SELECT allowed, revision FROM tool_grants WHERE principal_id='reader'").fetchone() == (0, 9) + seeded = {row[0] for row in db.execute("SELECT tool_name FROM tool_grants WHERE principal_id='*'")} + expected = {tool["name"] for tool in gateway_mcp.TOOLS} | {e["definition"]["name"] for e in knowledge_mcp.catalogue()["tools"]} + assert seeded == expected + assert "future_tool" not in seeded + db.close() + + +def test_concurrent_grant_change_refuses_discovery(fixture): + service, rows, *_, store = fixture + snapshots = [copy.deepcopy(rows), [grant("models_a", allowed=0), grant("models_b")]] + store.side_effect = lambda principal: snapshots.pop(0) + with pytest.raises(KnowledgeError) as caught: + service.discover([entry("models_a"), entry("models_b")], USER, {"query": "model"}) + assert caught.value.code == "tool_grants_changed" and caught.value.status == 409 + + +def test_cursor_chain_does_not_renew_ttl(fixture): + service, rows, _, clock, _ = fixture + rows.append(grant("models_c")) + entries = [entry("models_a"), entry("models_b"), entry("models_c")] + first = service.discover(entries, USER, {"query": "model", "limit": 1}) + clock[0] += 119 + second = service.discover(entries, USER, {"query": "model", "limit": 1, "cursor": first["nextCursor"]}) + clock[0] += 1 + with pytest.raises(KnowledgeError) as caught: + service.discover(entries, USER, {"query": "model", "limit": 1, "cursor": second["nextCursor"]}) + assert caught.value.code == "invalid_cursor" + + +def test_registered_knowledge_off_bytes_and_on_grant_authority(monkeypatch, fixture): + from routes import knowledge + app = Flask(__name__) + app.config.update(TESTING=True) + service, rows, *_ = fixture + app.extensions["deferred_tools"] = service + monkeypatch.setattr(knowledge, "api_authenticate_only", lambda **kwargs: lambda fn: fn) + knowledge.register_knowledge_routes(app, Mock(exempt=lambda fn: fn)) + @app.before_request + def identity(): + g.authenticated_user = USER + dispatch = Mock(return_value={"status": "ok"}) + monkeypatch.setattr(knowledge, "_dispatch", dispatch) + def post(method, params=None): + return app.test_client().post("/mcp", json={"jsonrpc": "2.0", "id": 1, "method": method, "params": params or {}}) + monkeypatch.setenv("DEFERRED_TOOLS_ENABLED", "false") + plain = post("tools/list") + monkeypatch.setenv("DEFERRED_TOOLS_ENABLED", "") + assert post("tools/list").data == plain.data + assert post("multillm.tools.discover", {"query": "technical"}).json["error"]["code"] == -32601 + monkeypatch.setenv("DEFERRED_TOOLS_ENABLED", "true") + rows[:] = [grant("knowledge_context", "knowledge:read")] + assert [t["name"] for t in post("tools/list").json["result"]["tools"]] == ["knowledge_context"] + response = post("tools/call", {"name": "knowledge_context", "arguments": {"query": "technical"}}) + assert response.status_code == 200 and response.json["result"]["isError"] is False + dispatch.assert_called_once() + dispatch.reset_mock() + for arguments in ({}, {"query": 1}, {"query": "technical", "extra": True}, [], None): + response = post("tools/call", {"name": "knowledge_context", "arguments": arguments}) + assert response.status_code == 400 and response.json["error"]["code"] == "invalid_arguments" + monkeypatch.setenv("MCP_CONTRACT_DIGESTS_ENABLED", "true") + response = app.test_client().post("/mcp", json={"jsonrpc": "2.0", "id": 1, "method": "tools/call", + "params": {"name": "knowledge_context", "arguments": {"query": "technical"}}}, + headers={"X-MultiLLM-MCP-Contract": "0" * 64}) + assert response.status_code == 409 and response.json["error"]["code"] == "mcp_contract_mismatch" + rows[:] = [] + response = post("tools/call", {"name": "knowledge_context", "arguments": {"query": "technical"}}) + assert response.status_code == 403 and response.json["error"]["code"] == "tool_not_granted" + rows[:] = [grant("knowledge_context", "knowledge:read"), grant("knowledge_search", "knowledge:read")] + first = post("multillm.tools.discover", {"query": "technical", "limit": 1}).json["result"] + second = post("multillm.tools.discover", {"query": "technical", "limit": 1, "cursor": first["nextCursor"]}).json["result"] + assert len(first["tools"]) == len(second["tools"]) == 1 + assert first["tools"][0]["name"] != second["tools"][0]["name"] + unknown = app.test_client().post("/mcp?toolsets=unknown", json={"jsonrpc": "2.0", "id": 1, + "method": "multillm.tools.discover", "params": {"query": "technical"}}) + assert unknown.json["error"]["code"] == -32602 + app.extensions["deferred_tools"] = deferred.DeferredTools(Mock(side_effect=sqlite3.OperationalError("no such table"))) + for method, params in [("tools/list", {}), ("tools/call", {"name": "knowledge_context", "arguments": {"query": "technical"}})]: + response = post(method, params) + assert response.status_code == 503 and response.is_json + dispatch.assert_not_called() + + +def test_registered_knowledge_disabled_calls_keep_bytes_and_error_order(monkeypatch): + from routes import knowledge + app = Flask(__name__) + monkeypatch.setattr(knowledge, "api_authenticate_only", lambda **kwargs: lambda fn: fn) + knowledge.register_knowledge_routes(app, Mock(exempt=lambda fn: fn)) + @app.before_request + def identity(): + g.authenticated_user = USER + monkeypatch.setattr(knowledge, "dispatch", Mock(return_value={"status": "ok"})) + monkeypatch.setenv("MCP_CONTRACT_DIGESTS_ENABLED", "true") + authority = Mock(side_effect=AssertionError("disabled grants read")) + app.extensions["deferred_tools"] = deferred.DeferredTools(authority) + cases = [("knowledge_context", {"query": "technical"}, None, 200, None), + ("knowledge_policy_update", {}, "0" * 64, 200, "insufficient_scope"), + ("knowledge_context", [], "0" * 64, 409, "mcp_contract_mismatch"), + ("knowledge_context", [], None, 200, -32602)] + for name, arguments, pin, status, code in cases: + def post(): + return app.test_client().post("/mcp", json={"jsonrpc": "2.0", "id": 1, "method": "tools/call", + "params": {"name": name, "arguments": arguments}}, + headers={"X-MultiLLM-MCP-Contract": pin} if pin else {}) + monkeypatch.setenv("DEFERRED_TOOLS_ENABLED", "false") + baseline = post() + assert baseline.status_code == status + if code == "insufficient_scope": + assert json.loads(baseline.json["result"]["content"][0]["text"])["error"]["code"] == code + elif code is not None: + assert baseline.json["error"]["code"] == code + for flag in ("", "0", "malformed"): + monkeypatch.setenv("DEFERRED_TOOLS_ENABLED", flag) + response = post() + assert (response.status_code, response.data, dict(response.headers)) == (baseline.status_code, baseline.data, dict(baseline.headers)) + authority.assert_not_called() + baseline = None + for flag in ("false", "", "0", "malformed"): + monkeypatch.setenv("DEFERRED_TOOLS_ENABLED", flag) + response = app.test_client().post("/mcp?toolsets=unknown", json={"jsonrpc": "2.0", "id": 1, + "method": "multillm.tools.discover", "params": {"query": "technical"}}) + assert response.json["error"]["code"] == -32601 + result = (response.status_code, response.data, dict(response.headers)) + baseline = result if baseline is None else baseline + assert result == baseline + + +@pytest.mark.parametrize("status", [404, 503]) +def test_private_grant_read_failures_are_json_503(monkeypatch, status): + from routes import knowledge + from services.intelligence_d1_store import PrivateIntelligenceError + monkeypatch.setenv("DEFERRED_TOOLS_ENABLED", "true") + monkeypatch.setattr(deferred.control_state_d1, "using_d1", lambda: True) + monkeypatch.setattr(deferred.control_state_d1, "call", Mock(side_effect=PrivateIntelligenceError(status, "storage_unavailable"))) + app = Flask(__name__) + app.extensions["deferred_tools"] = deferred.DeferredTools(deferred.D1GrantReader()) + monkeypatch.setattr(knowledge, "api_authenticate_only", lambda **kwargs: lambda fn: fn) + knowledge.register_knowledge_routes(app, Mock(exempt=lambda fn: fn)) + @app.before_request + def identity(): + g.authenticated_user = USER + for method, params in [("tools/list", {}), ("multillm.tools.discover", {"query": "technical"}), + ("tools/call", {"name": "knowledge_context", "arguments": {"query": "technical"}})]: + response = app.test_client().post("/mcp", json={"jsonrpc": "2.0", "id": 1, "method": method, "params": params}) + assert response.status_code == 503 and response.json["error"]["code"] == "tool_grants_unavailable" + + +def test_knowledge_argument_preflight_preserves_contract_pin(fixture, monkeypatch): + service, rows, *_ = fixture + rows[:] = [grant("knowledge_context", "knowledge:read")] + app = Flask(__name__) + app.extensions["deferred_tools"] = service + monkeypatch.setenv("DEFERRED_TOOLS_ENABLED", "true") + tool = next(e["definition"] for e in knowledge_mcp.catalogue()["tools"] if e["definition"]["name"] == "knowledge_context") + with app.app_context(): + knowledge_mcp.check_contract_pin("knowledge_context", drift.contract_digest(tool), enabled=True, + user=USER, arguments={"query": "technical"}) + with pytest.raises(KnowledgeError) as caught: + knowledge_mcp.check_contract_pin("knowledge_context", "0" * 64, enabled=True, + user=USER, arguments={"query": "technical"}) + assert caught.value.code == "mcp_contract_mismatch" + + +def test_private_grant_reader_uses_existing_allowlisted_state_endpoint(monkeypatch): + rows = [grant("list_models")] + monkeypatch.setattr(deferred.control_state_d1, "using_d1", lambda: True) + call = Mock(return_value={"version": 1, "grants": rows}) + monkeypatch.setattr(deferred.control_state_d1, "call", call) + assert deferred.D1GrantReader()("reader") == rows + call.assert_called_once_with("model_overrides", "tool_grants", principal="reader") + call.return_value = {"version": 2, "grants": rows} + with pytest.raises(KnowledgeError) as caught: + deferred.D1GrantReader()("reader") + assert caught.value.status == 503 diff --git a/tests/test_deferred_tools_worker.mjs b/tests/test_deferred_tools_worker.mjs new file mode 100644 index 00000000..6c4ff6e6 --- /dev/null +++ b/tests/test_deferred_tools_worker.mjs @@ -0,0 +1,305 @@ +import assert from "node:assert/strict"; +import test from "node:test"; +import { DatabaseSync } from "node:sqlite"; +import { readFileSync } from "node:fs"; +import { DeferredTools, deferredEnabled, readGrantSnapshot, handleDeferredMcp } from "../worker/knowledge/deferred-tools.mjs"; +import { catalogueDigest } from "../worker/knowledge/contract-drift.mjs"; +import { rankToolDefinitions } from "../worker/knowledge/skills-index.mjs"; +import * as deferred from "../worker/knowledge/deferred-tools.mjs"; +import { handleKnowledgeEdgeRequest } from "../worker/knowledge-edge.mjs"; +import { handleControlStateRequest } from "../worker/control-state-d1.mjs"; +import { generateIntegrationCredential } from "../scripts/intelligence_operator.mjs"; + +const catalogue = JSON.parse(readFileSync(new URL("../worker/knowledge-mcp-catalogue.json", import.meta.url), "utf8")); + +const principal = { id: "reader", scopes: ["knowledge:read"] }; +const entry = (name, description = "technical model search", schema = { type: "object", additionalProperties: false, properties: {} }) => + ({ scope: "knowledge:read", toolset: "core", definition: { name, description, inputSchema: schema } }); +const grant = (name, allowed = 1, id = "*") => + ({ principal_id: id, tool_name: name, scopes: ["knowledge:read"], allowed, revision: 1 }); +function fixture() { + const rows = [grant("models_a"), grant("models_b")], revision = [1], clock = [100]; + let reads = 0; + const service = new DeferredTools(async () => { reads++; return structuredClone(rows); }, { revision: () => revision[0], clock: () => clock[0] }); + return { service, rows, revision, clock, reads: () => reads }; +} + +test("permission filter precedes lexical ranking; exact principal denial overrides public grants", async () => { + const f = fixture(), entries = [entry("models_a"), entry("models_b"), entry("denied", "secret exact match")]; + assert.deepEqual((await f.service.discover(entries, principal, { query: "secret exact match" })).tools, []); + f.rows.push(grant("models_a", 0, "reader")); + assert.deepEqual((await f.service.listTools(entries, principal)).map(t => t.name), ["models_b"]); + assert.deepEqual(await f.service.listTools(entries, { ...principal, scopes: [] }), []); + assert.deepEqual(rankToolDefinitions(entries.slice(0, 2).map(e => e.definition), "model").map(t => t.name), ["models_a", "models_b"]); +}); + +test("granted unadvertised calls recheck grants and invoke full validator before dispatch", async () => { + const f = fixture(), tool = entry("models_a"); + let validated = 0; + const validate = (schema, args) => { validated++; assert.deepEqual(schema, tool.definition.inputSchema); return Object.keys(args).length === 0; }; + await f.service.authorizeCall(tool, principal, {}, validate); + await assert.rejects(f.service.authorizeCall(tool, principal, { extra: true }, validate), { code: "invalid_arguments" }); + await assert.rejects(f.service.authorizeCall(tool, principal, {}, undefined), { code: "tool_validation_unavailable", status: 503 }); + f.rows.push(grant("models_a", 0, "reader")); + await assert.rejects(f.service.authorizeCall(tool, principal, {}, validate), { code: "tool_not_granted", status: 403 }); + assert.equal(validated, 2); +}); + +test("complete schema byte budget paginates without modifying validation contracts", async () => { + const f = fixture(), entries = Array.from({ length: 20 }, (_, i) => entry(`models_${i}`, "model", { type: "object", description: "é".repeat(4000) })); + f.rows.splice(0, 2, ...entries.map(e => grant(e.definition.name))); + const first = await f.service.discover(entries, principal, { query: "model", limit: 16 }); + assert.ok(first.tools.length < 16); + assert.ok(Buffer.byteLength(JSON.stringify(first)) <= 65536); + const seen = first.tools.map(t => t.name); + assert.deepEqual(first.tools[0].inputSchema, entries[0].definition.inputSchema); + let cursor = first.nextCursor; + while (cursor) { + const page = await f.service.discover(entries, principal, { query: "model", limit: 16, cursor }); + seen.push(...page.tools.map(t => t.name)); cursor = page.nextCursor; + } + assert.equal(new Set(seen).size, 20); + entries[0].definition.inputSchema.description = "x".repeat(66000); + await assert.rejects(f.service.discover(entries.slice(0, 1), principal, { query: "model" }), { code: "tool_schema_too_large" }); +}); + +for (const change of ["tamper", "expiry", "principal", "query", "limit", "revision", "grants", "digest"]) { + test(`signed cursor rejects changed ${change}`, async () => { + const f = fixture(), entries = [entry("models_a"), entry("models_b")], args = { query: "model", limit: 1 }; + let cursor = (await f.service.discover(entries, principal, args)).nextCursor, user = principal; + if (change === "tamper") cursor = (cursor[0] === "A" ? "B" : "A") + cursor.slice(1); + else if (change === "expiry") f.clock[0] += 120; + else if (change === "principal") user = { ...principal, id: "other" }; + else if (change === "query") args.query = "search"; + else if (change === "limit") args.limit = 2; + else if (change === "revision") f.revision[0]++; + else if (change === "grants") f.rows[0].revision++; + else entries[0].definition.inputSchema.properties.new = { type: "string" }; + await assert.rejects(f.service.discover(entries, user, { ...args, cursor }), { code: "invalid_cursor" }); + }); +} + +test("bad inputs reject before storage and disabled adapter has no side effects", async () => { + const f = fixture(); + for (const params of [{}, { query: "" }, { query: "x", limit: 17 }, { query: "x", limit: true }, { query: "x", mode: "embedding" }]) { + await assert.rejects(f.service.discover([], principal, params), { code: "invalid_request" }); + } + let warnings = 0; + for (const flag of [undefined, "", "false", "0", "malformed"]) { + assert.equal(deferredEnabled(flag, () => warnings++), false); + assert.equal(await handleDeferredMcp({ method: "tools/list", id: 1 }, { DEFERRED_TOOLS_ENABLED: flag }, principal, [], { service: f.service }), null); + } + assert.equal(f.reads(), 0); + assert.equal(warnings, 1); +}); + +test("HTTP adapter supplies real errors, grant-filtered list and existing contract digests", async () => { + const f = fixture(), entries = [entry("models_a"), entry("models_b")]; + const env = { DEFERRED_TOOLS_ENABLED: "true", MCP_CONTRACT_DIGESTS_ENABLED: "true" }; + const response = await handleDeferredMcp({ method: "tools/list", id: 7 }, env, principal, entries, { service: f.service }); + assert.equal(response.status, 200); + const result = (await response.json()).result; + assert.equal(result._meta.contract_digest, await catalogueDigest(entries.map(e => e.definition))); + assert.ok(result.tools.every(t => t._meta.contract_digest)); + const missing = new DeferredTools(async () => { throw new Error("no such table"); }); + const failed = await handleDeferredMcp({ method: "multillm.tools.discover", id: 7, params: { query: "model" } }, env, principal, entries, { service: missing }); + assert.equal(failed.status, 503); assert.equal((await failed.json()).error.code, "tool_grants_unavailable"); +}); + +test("D1 snapshot uses model_grants revision and additive migration retains old rows", async t => { + const db = new DatabaseSync(":memory:"); t.after(() => db.close()); + db.exec("CREATE TABLE control_revisions(domain TEXT PRIMARY KEY, revision INTEGER, updated_at TEXT); INSERT INTO control_revisions VALUES('model_grants',7,'old')"); + const sql = readFileSync(new URL("../intelligence-migrations/0018_tool_grants.sql", import.meta.url), "utf8"); + db.exec(sql); db.prepare("INSERT INTO tool_grants VALUES(?,?,?,?,?)").run("reader", "models_a", '["knowledge:read"]', 0, 9); db.exec(sql); + const binding = { prepare: query => ({ bind: (...args) => ({ all: async () => ({ success: true, results: db.prepare(query).all(...args) }) }) }) }; + const snapshot = await readGrantSnapshot({ INTELLIGENCE_DB: binding, CONFIG_REVISION_SYNC_ENABLED: "true" }, principal.id); + assert.equal(snapshot.revision, 7); + assert.ok(snapshot.grants.some(g => g.tool_name === "models_a" && g.allowed === 0)); + assert.equal(db.prepare("SELECT revision FROM control_revisions WHERE domain='model_grants'").get().revision, 7); + assert.equal(db.prepare("SELECT count(*) AS n FROM tool_grants WHERE tool_name='future_tool'").get().n, 0); + db.exec("DROP TABLE tool_grants"); + await assert.rejects(readGrantSnapshot({ INTELLIGENCE_DB: binding }, principal.id), { code: "tool_grants_unavailable", status: 503 }); +}); + + +test("grant changes during discovery refuse the response", async () => { + const rows = [grant("models_a"), grant("models_b")]; let reads = 0; + const service = new DeferredTools(async () => reads++ === 0 ? rows : [grant("models_a", 0), grant("models_b")]); + await assert.rejects(service.discover([entry("models_a"), entry("models_b")], principal, { query: "model" }), { code: "tool_grants_changed", status: 409 }); +}); + +test("bounded validator recognizes every catalogue schema and rejects unsupported keywords in unused branches", () => { + for (const entry of catalogue.tools) assert.equal(typeof deferred.validateToolArguments(entry.definition.inputSchema, {}), "boolean", entry.definition.name); + for (const schema of [{ format: "uri" }, { anyOf: [{ type: "object" }, { unsupported: true }] }, { properties: { unused: { format: "uri" } } }]) { + assert.throws(() => deferred.validateToolArguments(schema, {}), { code: "tool_validation_unavailable", status: 503 }); + } + let nested = { type: "object" }; + for (let i = 0; i < 40; i++) nested = { properties: { child: nested } }; + assert.throws(() => deferred.validateToolArguments(nested, {}), { code: "tool_validation_unavailable", status: 503 }); + assert.throws(() => deferred.validateToolArguments({ uniqueItems: true }, Array.from({ length: 11000 }, (_, i) => i)), { code: "tool_validation_unavailable", status: 503 }); +}); + +test("validator enforces the complete supported keyword subset without leaking values", () => { + const cases = [ + [{ type: "object" }, [], false], [{ type: "integer" }, 1.5, false], [{ type: ["string", "null"] }, null, true], + [{ required: ["q"] }, {}, false], [{ properties: { q: { type: "string" } } }, { q: 1 }, false], + [{ additionalProperties: false, properties: { q: {} } }, { extra: 1 }, false], + [{ additionalProperties: { type: "integer" } }, { extra: "x" }, false], + [{ minLength: 2 }, "x", false], [{ maxLength: 1 }, "xy", false], [{ maxLength: 1 }, "😀", true], + [{ pattern: "^[a-z]+$" }, "1", false], [{ enum: ["a"] }, "b", false], + [{ enum: [{ a: 1, b: 2 }] }, { b: 2, a: 1 }, true], + [{ minimum: 2 }, 1, false], [{ maximum: 1 }, 2, false], + [{ items: { type: "integer" } }, ["x"], false], [{ minItems: 2 }, [1], false], [{ maxItems: 1 }, [1, 2], false], + [{ uniqueItems: true }, [{ a: 1, b: 2 }, { b: 2, a: 1 }], false], + [{ anyOf: [{ type: "string" }, { type: "number" }] }, false, false], + [{ oneOf: [{ type: "number" }, { type: "integer" }] }, 1, false], + [{ oneOf: [{ type: "string" }, { type: "integer" }] }, 1, true], + [{ default: "x", description: "annotation" }, {}, true], + ]; + for (const [schema, value, expected] of cases) assert.equal(deferred.validateToolArguments(schema, value), expected, JSON.stringify(schema)); + for (const schema of [{ type: "unknown" }, { pattern: "[" }, { minimum: "x" }, { items: [] }]) { + assert.throws(() => deferred.validateToolArguments(schema, "private-value"), error => error.status === 503 && !error.message.includes("private-value")); + } +}); + +test("dispatcher defaults to complete runtime validation and fails closed for unsupported schemas", async () => { + const f = fixture(), env = { DEFERRED_TOOLS_ENABLED: "true" }, tool = entry("models_a"); + const body = { id: 1, method: "tools/call", params: { name: "models_a", arguments: {} } }; + assert.equal(await handleDeferredMcp(body, env, principal, [tool], { service: f.service }), null); + const invalid = await handleDeferredMcp({ ...body, params: { ...body.params, arguments: { extra: "private-value" } } }, env, principal, [tool], { service: f.service }); + assert.equal(invalid.status, 400); assert.ok(!(await invalid.text()).includes("private-value")); + tool.definition.inputSchema.format = "unknown"; + const unsupported = await handleDeferredMcp(body, env, principal, [tool], { service: f.service }); + assert.equal(unsupported.status, 503); assert.equal((await unsupported.json()).error.code, "tool_validation_unavailable"); +}); + +function edgeFixture() { + const dispatched = [], rows = [grant("knowledge_context"), grant("knowledge_search")]; + const env = { ADMIN_API_KEY: "synthetic-deferred-key", ADMIN_USERNAME: "reader", MCP_CONTRACT_DIGESTS_ENABLED: "true", + INTELLIGENCE_DB: { prepare(sql) { + assert.match(sql, /FROM tool_grants/); + return { bind: id => ({ all: async () => ({ success: true, results: rows.filter(row => ["*", id].includes(row.principal_id)) + .map(({ scopes, ...row }) => ({ ...row, scopes_json: JSON.stringify(scopes) })) }) }) }; + } }, KNOWLEDGE_SERVICE: { async fetch(url, init) { + dispatched.push(JSON.parse(init.body)); return Response.json({ version: 1, result: { status: "ok" } }); + } } }; + const post = (method, params = {}, { pin, toolsets, key = env.ADMIN_API_KEY } = {}) => handleKnowledgeEdgeRequest(new Request( + `https://gateway.example/mcp${toolsets === undefined ? "" : `?toolsets=${toolsets}`}`, { method: "POST", + headers: { authorization: `Bearer ${key}`, "content-type": "application/json", ...(pin ? { "X-MultiLLM-MCP-Contract": pin } : {}) }, + body: JSON.stringify({ jsonrpc: "2.0", id: 7, method, params }) }), env); + return { env, rows, dispatched, post }; +} + +test("edge handleMcp keeps disabled bytes and error order without grant reads", async () => { + const f = edgeFixture(); + f.env.INTELLIGENCE_DB.prepare = () => { throw new Error("disabled grants read"); }; + for (const [method, params, options] of [["tools/call", { name: "knowledge_context", arguments: { query: "technical" } }, {}], + ["tools/call", { name: "knowledge_context", arguments: [] }, {}], + ["tools/call", { name: "knowledge_context", arguments: [] }, { pin: "0".repeat(64) }], + ["multillm.tools.discover", { query: "technical" }, { toolsets: "unknown" }], ["tools/list", {}, {}]]) { + f.env.DEFERRED_TOOLS_ENABLED = "false"; + const baseline = await f.post(method, params, options), bytes = await baseline.text(); + for (const flag of [undefined, "", "0", "bad"]) { + f.env.DEFERRED_TOOLS_ENABLED = flag; + const response = await f.post(method, params, options); + assert.equal(response.status, baseline.status); assert.equal(await response.text(), bytes); + assert.deepEqual([...response.headers], [...baseline.headers]); + } + } +}); + +test("edge handleMcp checks grants and arguments before dispatch and pages filtered discovery", async () => { + const f = edgeFixture(); f.env.DEFERRED_TOOLS_ENABLED = "true"; + const denied = await f.post("tools/call", { name: "knowledge_exa_search", arguments: { query: "technical" } }); + assert.equal(denied.status, 403); assert.equal((await denied.json()).error.code, "tool_not_granted"); + for (const args of [{}, { query: 1 }, { query: "technical", extra: true }, null, []]) { + const invalid = await f.post("tools/call", { name: "knowledge_context", arguments: args }); + assert.equal(invalid.status, 400); assert.equal((await invalid.json()).error.code, "invalid_arguments"); + } + assert.equal(f.dispatched.length, 0); + assert.equal((await f.post("tools/call", { name: "knowledge_context", arguments: { query: "technical" } })).status, 200); + assert.equal(f.dispatched.length, 1); + const pinned = await f.post("tools/call", { name: "knowledge_context", arguments: { query: "technical" } }, { pin: "0".repeat(64) }); + assert.equal(pinned.status, 409); assert.equal(f.dispatched.length, 1); + const list = (await (await f.post("tools/list", {}, { toolsets: "core" })).json()).result; + assert.deepEqual(list.tools.map(tool => tool.name), ["knowledge_context", "knowledge_search"]); + assert.ok(list.tools.every(tool => tool._meta.contract_digest)); + const first = (await (await f.post("multillm.tools.discover", { query: "technical", limit: 1 })).json()).result; + const second = (await (await f.post("multillm.tools.discover", { query: "technical", limit: 1, cursor: first.nextCursor })).json()).result; + assert.notEqual(first.tools[0].name, second.tools[0].name); + for (const method of ["tools/list", "multillm.tools.discover", "tools/call"]) { + const response = await f.post(method, { query: "technical" }, { toolsets: "unknown" }); + assert.equal((await response.json()).error.code, -32602); + } + f.env.INTELLIGENCE_DB.prepare = () => { throw new Error("no such table"); }; + for (const method of ["tools/list", "multillm.tools.discover", "tools/call"]) { + const response = await f.post(method, method === "tools/call" ? { name: "knowledge_context", arguments: { query: "technical" } } : { query: "technical" }); + assert.equal(response.status, 503); assert.equal((await response.json()).error.code, "tool_grants_unavailable"); + } +}); + +test("disabled edge scope denial keeps bytes and precedes contract pins and argument checks", async () => { + const f = edgeFixture(), credential = await generateIntegrationCredential(); + f.env.AUTH_STORAGE_BACKEND = "d1"; + f.env.INTELLIGENCE_DB.prepare = sql => { + assert.ok(!sql.includes("tool_grants")); + return { bind: () => ({ first: async () => ({ id: "integration:reader", scopes: '["knowledge:read"]', version: 1, + created_at: "2026-09-24T00:00:00Z", revoked_at: null, key_prefix: credential.keyPrefix, key_hash: credential.keyHash }) }) }; + }; + let bytes; + for (const flag of [undefined, "false", "", "bad"]) { + f.env.DEFERRED_TOOLS_ENABLED = flag; + const response = await f.post("tools/call", { name: "knowledge_policy_update", arguments: [] }, { pin: "0".repeat(64), key: credential.key }); + assert.equal(response.status, 200); + const text = await response.text(), body = JSON.parse(text); + assert.equal(JSON.parse(body.result.content[0].text).error.code, "insufficient_scope"); + bytes ??= text; assert.equal(text, bytes); + } + assert.equal(f.dispatched.length, 0); +}); + +test("private model-state tool_grants read is gated, bounded and fails closed", async () => { + const f = edgeFixture(); + f.rows.push(grant("knowledge_context", 0, "reader"), grant("knowledge_context", 1, "other")); + const queries = [], prepare = f.env.INTELLIGENCE_DB.prepare; + f.env.INTELLIGENCE_DB.prepare = sql => { queries.push(sql); return prepare(sql); }; + const call = (principal = "reader", extra = {}) => handleControlStateRequest(new Request("http://intelligence.internal/v1/state/models", { + method: "POST", headers: { "content-type": "application/json" }, + body: JSON.stringify({ version: 1, operation: "tool_grants", principal, ...extra }) }), f.env); + assert.equal((await call()).status, 503); assert.equal(queries.length, 0); + f.env.DEFERRED_TOOLS_ENABLED = "true"; + assert.deepEqual(await (await call()).json(), { version: 1, grants: f.rows.slice(0, 3) }); + assert.match(queries[0], /LIMIT 4097/); + for (const [id, extra] of [["*", {}], ["", {}], ["reader", { extra: true }]]) assert.equal((await call(id, extra)).status, 400); + f.rows.splice(0, f.rows.length, ...Array.from({ length: 4097 }, (_, i) => grant(`tool_${i}`))); + assert.equal((await call()).status, 503); + f.env.INTELLIGENCE_DB.prepare = () => { throw new Error("no such table"); }; + const missing = await call(); assert.equal(missing.status, 503); + assert.equal((await missing.json()).error.code, "tool_grants_unavailable"); +}); + +test("revocation during async schema validation refuses execution", async () => { + const f = fixture(); + await assert.rejects(f.service.authorizeCall(entry("models_a"), principal, {}, async () => { + f.rows.push(grant("models_a", 0, "reader")); return true; + }), { code: "tool_not_granted", status: 403 }); +}); + +test("cursor page chains retain the initial expiry", async () => { + const f = fixture(), entries = [entry("models_a"), entry("models_b"), entry("models_c")]; + f.rows.push(grant("models_c")); + const first = await f.service.discover(entries, principal, { query: "model", limit: 1 }); + f.clock[0] += 119; + const second = await f.service.discover(entries, principal, { query: "model", limit: 1, cursor: first.nextCursor }); + f.clock[0]++; + await assert.rejects(f.service.discover(entries, principal, { query: "model", limit: 1, cursor: second.nextCursor }), { code: "invalid_cursor" }); +}); + +test("HTTP call preflight permits an unadvertised grant and returns real permission errors", async () => { + const f = fixture(), entries = [entry("models_a")], env = { DEFERRED_TOOLS_ENABLED: "true" }; + const body = { method: "tools/call", id: 1, params: { name: "models_a", arguments: {} } }; + assert.equal(await handleDeferredMcp(body, env, principal, entries, { service: f.service, validate: () => true }), null); + f.rows.push(grant("models_a", 0, "reader")); + const denied = await handleDeferredMcp(body, env, principal, entries, { service: f.service, validate: () => true }); + assert.equal(denied.status, 403); assert.equal((await denied.json()).error.code, "tool_not_granted"); +}); diff --git a/worker/container-env.mjs b/worker/container-env.mjs index 241cf668..17a010fd 100644 --- a/worker/container-env.mjs +++ b/worker/container-env.mjs @@ -27,6 +27,7 @@ const DIRECT_ENV_KEYS = [ "INTELLIGENCE_NANOGPT_SUBSCRIPTION_API_KEY", "WORKBENCH_WORKER_URL", "MCP_CONTRACT_DIGESTS_ENABLED", + "DEFERRED_TOOLS_ENABLED", "CONNECTION_PROFILES_DB_PATH", "CONFIG_REVISION_SYNC_ENABLED", "CONFIG_SYNC_TTL_SECONDS", diff --git a/worker/control-state-d1.mjs b/worker/control-state-d1.mjs index 3bfaf35e..b17b6c28 100644 --- a/worker/control-state-d1.mjs +++ b/worker/control-state-d1.mjs @@ -136,6 +136,15 @@ async function login(db, body) { } async function models(db, body, env) { + if (body.operation === "tool_grants") { + if (!fields(body, ["version", "operation", "principal"]) || !text(body.principal, 128) || body.principal === "*") return null; + const { deferredEnabled, readGrantSnapshot } = await import("./knowledge/deferred-tools.mjs"); + if (!deferredEnabled(env.DEFERRED_TOOLS_ENABLED)) return reply({ error: "tool_grants_unavailable" }, 503); + try { + const { grants } = await readGrantSnapshot(env, body.principal); + return reply({ grants }); + } catch { return reply({ error: "tool_grants_unavailable" }, 503); } + } if (body.operation === "revisions") { if (!revisionSyncSettings(env).enabled) return reply({ error: "not_found" }, 404); return handleRevisionMetadata(db, body); diff --git a/worker/d1-schema.mjs b/worker/d1-schema.mjs index 4a0a37b0..64b5799f 100644 --- a/worker/d1-schema.mjs +++ b/worker/d1-schema.mjs @@ -10,7 +10,7 @@ export const REQUIRED_D1_TABLES = Object.freeze(["intelligence_policy", "intelli "usage_events", "usage_daily", "usage_batches", "media_jobs", "media_job_items", "shadow_eval_samples", "shadow_eval_results", "shadow_eval_config", "shadow_eval_policy_backups", "prompt_templates", - "config_snapshot_revisions", "config_snapshots", "config_snapshot_applications", "control_revisions"]); + "config_snapshot_revisions", "config_snapshots", "config_snapshot_applications", "control_revisions", "tool_grants"]); /** * Readiness for the D1 schema. A deploy that skipped `wrangler d1 migrations apply` reports diff --git a/worker/knowledge-edge.mjs b/worker/knowledge-edge.mjs index 0912bcd2..572daf60 100644 --- a/worker/knowledge-edge.mjs +++ b/worker/knowledge-edge.mjs @@ -14,6 +14,7 @@ import { INTEGRATION_SCOPES, lookupIntegrationPrincipal } from "./intelligence-a import { logFailure } from "./log.mjs"; import { contractPinMismatch, digestsEnabled, discoveryContract } from "./knowledge/contract-drift.mjs"; import { SYNC_REQUEST_BYTES } from "./knowledge/skills-validation.mjs"; +import { deferredEnabled, handleDeferredMcp, validateToolArguments } from "./knowledge/deferred-tools.mjs"; import { protectPayload, secretScanMode, SECRET_SCAN_HEADER } from "./secret-firewall.mjs"; const KNOWLEDGE_SCOPES = ["knowledge:read", "knowledge:manage"]; @@ -395,6 +396,15 @@ async function handleMcp(request, env, principal) { return method.startsWith("notifications/") ? new Response(null, { status: 202, headers: noStore }) : rpcError(null, -32600, "An MCP request requires an id.", 400); } + if (deferredEnabled(env.DEFERRED_TOOLS_ENABLED)) { + const requested = new URL(request.url).searchParams.get("toolsets"); + const toolsets = requested === null ? null : [...new Set(requested.split(",").map(name => name.trim()).filter(Boolean))]; + if (toolsets && (!toolsets.length || toolsets.some(name => !catalogue.toolsets.includes(name)))) { + return rpcError(id, -32602, `Unknown toolset. Use any of: ${catalogue.toolsets.join(", ")}.`); + } + const response = await handleDeferredMcp(body, env, principal, catalogue.tools, { toolsets, validate: validateToolArguments }); + if (response !== null) return response; + } if (method === "initialize") { if (typeof params.protocolVersion !== "string" || !isRecord(params.capabilities ?? {}) || !isRecord(params.clientInfo ?? {})) { return rpcError(id, -32602, "Initialize requires a protocolVersion string."); diff --git a/worker/knowledge/deferred-tools.mjs b/worker/knowledge/deferred-tools.mjs new file mode 100644 index 00000000..a591d5b2 --- /dev/null +++ b/worker/knowledge/deferred-tools.mjs @@ -0,0 +1,336 @@ +/** Permission-first discovery; no provider calls, embeddings or cached authorization. */ +import { KnowledgeError, isRecord, fail } from "./contracts.mjs"; +import { catalogueDigest, contractDigest, digestsEnabled } from "./contract-drift.mjs"; +import { rankToolDefinitions } from "./skills-index.mjs"; +import { revisionSyncSettings } from "../config-revision.mjs"; + +export const MAX_DISCOVERY_BYTES = 64 * 1024; +export const CURSOR_TTL_SECONDS = 120; +const MAX_GRANTS = 4096; +const RPC_ENVELOPE_RESERVE = 4096; +const processRevision = crypto.randomUUID(); +const encoder = new TextEncoder(); +const services = new WeakMap(); +let warned = false; + +export function deferredEnabled(value, warn = message => console.warn(message)) { + if (typeof value === "boolean") return value; + if (value === undefined || value === null) return false; + if (typeof value === "string") { + const flag = value.trim().toLowerCase(); + if (["", "0", "false", "off", "no"].includes(flag)) return false; + if (["1", "true", "on", "yes"].includes(flag)) return true; + } + if (!warned) { warn("Invalid DEFERRED_TOOLS_ENABLED; deferred tools disabled"); warned = true; } + return false; +} + +const unavailable = () => new KnowledgeError("tool_grants_unavailable", "The tool grant authority is unavailable. No tool was executed.", 503); +const hex = bytes => [...new Uint8Array(bytes)].map(byte => byte.toString(16).padStart(2, "0")).join(""); +const hash = async value => hex(await crypto.subtle.digest("SHA-256", encoder.encode(JSON.stringify(value)))); +const base64 = bytes => btoa(String.fromCharCode(...bytes)).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/, ""); + +function identity(user) { + const id = user?.id || user?.username, scopes = user?.scopes ?? []; + if (typeof id !== "string" || !id || id.length > 128 || id === "*" || !Array.isArray(scopes) + || scopes.some(scope => typeof scope !== "string")) fail("invalid_principal", "The authenticated identity is unavailable.", 403); + return { id, scopes: user.is_admin ? ["admin"] : scopes }; +} + +function parseDiscovery(params) { + if (!isRecord(params) || Object.keys(params).some(key => !["query", "cursor", "limit"].includes(key))) { + fail("invalid_request", "Discovery accepts query, cursor and limit only."); + } + const { query, cursor } = params, limit = Object.hasOwn(params, "limit") ? params.limit : 16; + if (typeof query !== "string" || !query.trim() || [...query].length > 500 || !query.isWellFormed() + || /[\x00-\x1f\x7f]/.test(query) || !Number.isSafeInteger(limit) || limit < 1 || limit > 16 + || cursor !== undefined && cursor !== null && (typeof cursor !== "string" || !cursor || cursor.length > 4096)) { + fail("invalid_request", "Use a query up to 500 characters, limit 1–16 and a valid cursor."); + } + return { query: query.trim().toLowerCase(), limit, cursor }; +} + +function validatedGrants(rows, id) { + if (!Array.isArray(rows) || rows.length > MAX_GRANTS) throw unavailable(); + const grants = new Map(); + for (const row of rows) { + if (!isRecord(row) || !["*", id].includes(row.principal_id) || typeof row.tool_name !== "string" + || !row.tool_name || row.tool_name.length > 128 || ![0, 1].includes(row.allowed) + || !Number.isSafeInteger(row.revision) || row.revision < 0 || !Array.isArray(row.scopes) || !row.scopes.length + || row.scopes.some(scope => typeof scope !== "string" || !scope || scope.length > 80)) throw unavailable(); + const key = JSON.stringify([row.principal_id, row.tool_name]); + if (grants.has(key)) throw unavailable(); + grants.set(key, { principal_id: row.principal_id, tool_name: row.tool_name, scopes: row.scopes, allowed: row.allowed, revision: row.revision }); + } + return grants; +} + +function permitted(entry, principal, grants) { + if (!principal.scopes.includes("admin") && !principal.scopes.includes(entry.scope)) return false; + const name = entry.definition.name; + const row = grants.get(JSON.stringify([principal.id, name])) ?? grants.get(JSON.stringify(["*", name])); + return Boolean(row?.allowed && (principal.scopes.includes("admin") || row.scopes.every(scope => principal.scopes.includes(scope)))); +} + +/** A fixed read-only D1 collaborator, also usable by the private Container dispatcher. */ +export async function readGrantSnapshot(env, principalId) { + try { + identity({ id: principalId, scopes: [] }); + const db = env.INTELLIGENCE_DB; + if (!db?.prepare) throw unavailable(); + const statements = [db.prepare("SELECT principal_id, tool_name, scopes_json, allowed, revision FROM tool_grants WHERE principal_id IN ('*', ?) ORDER BY principal_id, tool_name LIMIT 4097").bind(principalId)]; + const revisionEnabled = revisionSyncSettings(env).enabled; + if (revisionEnabled) statements.push(db.prepare("SELECT COALESCE((SELECT revision FROM control_revisions WHERE domain=?), 0) AS revision").bind("model_grants")); + const results = db.batch ? await db.batch(statements) : await Promise.all(statements.map(statement => statement.all())); + if (results.some(result => result.success === false || !Array.isArray(result.results))) throw unavailable(); + const grants = results[0].results.map(row => ({ principal_id: row.principal_id, tool_name: row.tool_name, + scopes: JSON.parse(row.scopes_json), allowed: row.allowed, revision: row.revision })); + validatedGrants(grants, principalId); + const revision = revisionEnabled ? results[1].results[0]?.revision : processRevision; + if (revisionEnabled && (!Number.isSafeInteger(revision) || revision < 0)) throw unavailable(); + return { grants, revision }; + } catch { throw unavailable(); } +} + +export class DeferredTools { + constructor(readGrants, { revision = null, clock = () => Date.now() / 1000 } = {}) { + this.readGrants = readGrants; this.revision = revision; this.clock = clock; + this.key = crypto.subtle.generateKey({ name: "HMAC", hash: "SHA-256", length: 256 }, false, ["sign", "verify"]); + } + + async snapshot(principal) { + try { + const value = await this.readGrants(principal.id); + const grants = validatedGrants(Array.isArray(value) ? value : value.grants, principal.id); + const revision = this.revision ? await this.revision() : value.revision ?? processRevision; + if (!(typeof revision === "string" && revision || Number.isSafeInteger(revision) && revision >= 0)) throw unavailable(); + const rows = [...grants.entries()].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([, row]) => row); + return { grants, revision, stamp: await hash(rows) }; + } catch (error) { + if (error instanceof KnowledgeError) throw error; + throw unavailable(); + } + } + + async listTools(entries, user) { + const principal = identity(user), { grants } = await this.snapshot(principal); + return entries.filter(entry => permitted(entry, principal, grants)).map(entry => entry.definition); + } + + async authorizeCall(entry, user, arguments_, validate) { + const principal = identity(user), { grants } = await this.snapshot(principal); + if (!permitted(entry, principal, grants)) fail("tool_not_granted", "The key is not granted permission for this tool.", 403); + if (typeof validate !== "function") fail("tool_validation_unavailable", "The complete runtime schema validator is unavailable.", 503); + let valid; + try { valid = isRecord(arguments_) && await validate(entry.definition.inputSchema, arguments_, entry); } + catch (error) { + if (error instanceof KnowledgeError) throw error; + fail("tool_validation_unavailable", "The complete runtime schema validator is unavailable.", 503); + } + if (valid !== true) fail("invalid_arguments", "The arguments do not match the complete runtime tool schema."); + const latest = await this.snapshot(principal); + if (!permitted(entry, principal, latest.grants)) fail("tool_not_granted", "The key is not granted permission for this tool.", 403); + } + + async sign(payload) { + const encoded = base64(encoder.encode(JSON.stringify(payload))); + return `${encoded}.${hex(await crypto.subtle.sign("HMAC", await this.key, encoder.encode(encoded)))}`; + } + + async decode(cursor, binding, count) { + try { + const [encoded, signature, extra] = cursor.split("."); + if (extra !== undefined || !/^[A-Za-z0-9_-]+$/.test(encoded) || !/^[a-f0-9]{64}$/.test(signature ?? "")) throw new Error(); + const bytes = Uint8Array.from(signature.match(/../g), byte => Number.parseInt(byte, 16)); + if (!await crypto.subtle.verify("HMAC", await this.key, bytes, encoder.encode(encoded))) throw new Error(); + const raw = atob(encoded.replaceAll("-", "+").replaceAll("_", "/") + "=".repeat((4 - encoded.length % 4) % 4)); + const payload = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(Uint8Array.from(raw, char => char.charCodeAt(0)))); + if (!isRecord(payload) || Object.keys(payload).length !== Object.keys(binding).length + 2 + || Object.entries(binding).some(([key, value]) => payload[key] !== value) + || !Number.isSafeInteger(payload.o) || payload.o < 1 || payload.o >= count + || !Number.isFinite(payload.exp) || payload.exp <= this.clock() || payload.exp > this.clock() + CURSOR_TTL_SECONDS) throw new Error(); + return { offset: payload.o, expires: payload.exp }; + } catch { fail("invalid_cursor", "The discovery cursor expired or its permissions or contract changed."); } + } + + async discover(entries, user, params, { digests = false } = {}) { + const { query, limit, cursor } = parseDiscovery(params), principal = identity(user); + const { grants, revision, stamp } = await this.snapshot(principal); + let tools = entries.filter(entry => permitted(entry, principal, grants)).map(entry => entry.definition); + let digest; + try { digest = await catalogueDigest(tools); } + catch { fail("tool_schema_too_large", "The authorized tool catalogue exceeds contract digest limits.", 413); } + if (digests) tools = await Promise.all(tools.map(async tool => ({ ...tool, _meta: { ...tool._meta, contract_digest: await contractDigest(tool) } }))); + const ranked = rankToolDefinitions(tools, query); + const binding = { v: 1, p: await hash(principal), d: digest, r: revision, g: stamp, q: await hash(query), l: limit }; + const { offset, expires } = cursor ? await this.decode(cursor, binding, ranked.length) + : { offset: 0, expires: this.clock() + CURSOR_TTL_SECONDS }; + let page = { tools: [], _meta: { contract_digest: digest } }; + for (let end = offset + 1; end <= Math.min(ranked.length, offset + limit); end++) { + const candidate = { tools: ranked.slice(offset, end), _meta: page._meta }; + if (end < ranked.length) candidate.nextCursor = await this.sign({ ...binding, o: end, exp: expires }); + if (encoder.encode(JSON.stringify(candidate)).length + RPC_ENVELOPE_RESERVE > MAX_DISCOVERY_BYTES) { + if (!page.tools.length) fail("tool_schema_too_large", "A complete tool schema cannot fit in a discovery response.", 413); + break; + } + page = candidate; + } + const latest = await this.snapshot(principal); + if (revision !== latest.revision || stamp !== latest.stamp) fail("tool_grants_changed", "Tool grants changed during discovery. Start discovery again.", 409); + return page; + } +} + +function runtimeService(env) { + if (!services.has(env)) services.set(env, new DeferredTools(id => readGrantSnapshot(env, id))); + return services.get(env); +} + +const SCHEMA_KEYWORDS = new Set(["type", "required", "properties", "additionalProperties", "minLength", "maxLength", + "pattern", "enum", "minimum", "maximum", "items", "minItems", "maxItems", "uniqueItems", "anyOf", "oneOf", "default", "description"]); +const SCHEMA_TYPES = new Set(["object", "array", "string", "number", "integer", "boolean", "null"]); +const validationUnavailable = () => fail("tool_validation_unavailable", "The complete runtime schema validator is unavailable.", 503); + +function validationBudget() { + let work = 0, nodes = 0, characters = 0; + const spend = (depth = 0) => { if (++work > 65536 || depth > 32) validationUnavailable(); }; + const inspect = (value, depth = 0) => { + spend(depth); + if (++nodes > 8192) validationUnavailable(); + if (typeof value === "string") { + characters += value.length; + if (characters > 262144 || !value.isWellFormed()) validationUnavailable(); + } else if (typeof value === "number") { + if (!Number.isFinite(value)) validationUnavailable(); + } else if (Array.isArray(value)) { + for (const item of value) inspect(item, depth + 1); + } else if (isRecord(value)) { + for (const [key, item] of Object.entries(value)) { inspect(key, depth + 1); inspect(item, depth + 1); } + } else if (value !== null && typeof value !== "boolean") validationUnavailable(); + }; + const canonical = (value, depth = 0) => { + spend(depth); + if (Array.isArray(value)) return `[${value.map(item => canonical(item, depth + 1)).join(",")}]`; + if (isRecord(value)) return `{${Object.keys(value).sort().map(key => `${JSON.stringify(key)}:${canonical(value[key], depth + 1)}`).join(",")}}`; + return JSON.stringify(value); + }; + return { spend, inspect, canonical, patterns: new Map(), enums: new Map() }; +} + +function compileRuntimeSchema(node, budget, depth = 0) { + const { spend, canonical, patterns, enums } = budget; + spend(depth); + if (typeof node === "boolean") return; + if (!isRecord(node) || Object.keys(node).some(key => !SCHEMA_KEYWORDS.has(key))) validationUnavailable(); + for (const [key, value] of Object.entries(node)) { + spend(); + if (key === "type") { + const types = Array.isArray(value) ? value : [value]; + if (!types.length || types.some(type => !SCHEMA_TYPES.has(type)) || new Set(types).size !== types.length) validationUnavailable(); + } else if (key === "required") { + if (!Array.isArray(value) || value.some(name => typeof name !== "string") || new Set(value).size !== value.length) validationUnavailable(); + } else if (key === "properties") { + if (!isRecord(value)) validationUnavailable(); + for (const child of Object.values(value)) compileRuntimeSchema(child, budget, depth + 1); + } else if (["items", "additionalProperties"].includes(key)) { + compileRuntimeSchema(value, budget, depth + 1); + } else if (["anyOf", "oneOf"].includes(key)) { + if (!Array.isArray(value) || !value.length) validationUnavailable(); + for (const child of value) compileRuntimeSchema(child, budget, depth + 1); + } else if (["minLength", "maxLength", "minItems", "maxItems"].includes(key)) { + if (!Number.isSafeInteger(value) || value < 0) validationUnavailable(); + } else if (["minimum", "maximum"].includes(key)) { + if (typeof value !== "number" || !Number.isFinite(value)) validationUnavailable(); + } else if (key === "uniqueItems") { + if (typeof value !== "boolean") validationUnavailable(); + } else if (key === "enum") { + if (!Array.isArray(value) || !value.length) validationUnavailable(); + const options = new Set(value.map(item => canonical(item))); + if (options.size !== value.length) validationUnavailable(); + enums.set(node, options); + } else if (key === "pattern") { + if (typeof value !== "string" || value.length > 512) validationUnavailable(); + try { patterns.set(node, new RegExp(value, "u")); } + catch { validationUnavailable(); } + } else if (key === "description" && typeof value !== "string") validationUnavailable(); + } +} + +function matchesType(type, value) { + if (type === "object") return isRecord(value); + if (type === "array") return Array.isArray(value); + if (type === "null") return value === null; + if (type === "integer") return typeof value === "number" && Number.isInteger(value); + return typeof value === type; +} + +function matchesRuntimeSchema(node, value, budget, depth = 0) { + const { spend, canonical, patterns, enums } = budget; + spend(depth); + if (typeof node === "boolean") return node; + if (node.type !== undefined && !(Array.isArray(node.type) ? node.type : [node.type]).some(type => matchesType(type, value))) return false; + if (enums.has(node) && !enums.get(node).has(canonical(value))) return false; + if (node.anyOf && !node.anyOf.some(child => matchesRuntimeSchema(child, value, budget, depth + 1))) return false; + if (node.oneOf && node.oneOf.filter(child => matchesRuntimeSchema(child, value, budget, depth + 1)).length !== 1) return false; + if (typeof value === "string") { + const length = [...value].length; + spend(); + if (node.minLength !== undefined && length < node.minLength || node.maxLength !== undefined && length > node.maxLength) return false; + // Patterns come from the static, reviewed catalogue, never from request arguments. + if (patterns.has(node) && !patterns.get(node).test(value)) return false; + } else if (typeof value === "number") { + if (node.minimum !== undefined && value < node.minimum || node.maximum !== undefined && value > node.maximum) return false; + } else if (Array.isArray(value)) { + if (node.minItems !== undefined && value.length < node.minItems || node.maxItems !== undefined && value.length > node.maxItems) return false; + if (node.uniqueItems) { + const seen = new Set(); + for (const item of value) { const key = canonical(item); if (seen.has(key)) return false; seen.add(key); } + } + if (node.items !== undefined && !value.every(item => matchesRuntimeSchema(node.items, item, budget, depth + 1))) return false; + } else if (isRecord(value)) { + if (node.required?.some(name => !Object.hasOwn(value, name))) return false; + const properties = node.properties ?? {}; + for (const [key, item] of Object.entries(value)) { + spend(); + if (Object.hasOwn(properties, key)) { + if (!matchesRuntimeSchema(properties[key], item, budget, depth + 1)) return false; + } else if (node.additionalProperties !== undefined && !matchesRuntimeSchema(node.additionalProperties, item, budget, depth + 1)) return false; + } + } + return true; +} + +/** Validate the static catalogue subset; unsupported schemas and exhausted budgets fail closed. */ +export function validateToolArguments(schema, arguments_) { + const budget = validationBudget(); + budget.inspect(schema); budget.inspect(arguments_); + compileRuntimeSchema(schema, budget); + return matchesRuntimeSchema(schema, arguments_, budget); +} + +/** Return a JSON-RPC response, or null to continue the existing dispatcher after preflight. */ +export async function handleDeferredMcp(body, env, principal, entries, { service = null, validate = validateToolArguments, toolsets = null } = {}) { + if (!deferredEnabled(env.DEFERRED_TOOLS_ENABLED) || !["tools/list", "tools/call", "multillm.tools.discover"].includes(body.method)) return null; + const respond = (field, value, status = 200) => Response.json({ jsonrpc: "2.0", id: body.id, [field]: value }, + { status, headers: { "cache-control": "no-store" } }); + try { + const authority = service ?? runtimeService(env); + if (body.method === "tools/call") { + const entry = entries.find(entry => entry.definition.name === body.params?.name); + if (!entry) return null; + const arguments_ = Object.hasOwn(body.params ?? {}, "arguments") ? body.params.arguments : {}; + await authority.authorizeCall(entry, principal, arguments_, validate); + return null; + } + const selected = entries.filter(entry => toolsets === null || toolsets.includes(entry.toolset)); + if (body.method === "multillm.tools.discover") return respond("result", await authority.discover(selected, principal, body.params ?? {}, { digests: digestsEnabled(env.MCP_CONTRACT_DIGESTS_ENABLED) })); + const tools = await authority.listTools(selected, principal); + const result = digestsEnabled(env.MCP_CONTRACT_DIGESTS_ENABLED) + ? { tools: await Promise.all(tools.map(async tool => ({ ...tool, _meta: { ...tool._meta, contract_digest: await contractDigest(tool) } }))), + _meta: { contract_digest: await catalogueDigest(tools) } } : { tools }; + return respond("result", result); + } catch (error) { + if (!(error instanceof KnowledgeError)) throw error; + return respond("error", { code: error.code, message: error.message }, error.status); + } +} diff --git a/worker/knowledge/skills-index.mjs b/worker/knowledge/skills-index.mjs index 51afe58d..989b5d33 100644 --- a/worker/knowledge/skills-index.mjs +++ b/worker/knowledge/skills-index.mjs @@ -92,3 +92,14 @@ export class SkillsIndex { return results.sort((a, b) => b.score - a.score || a.skill_id.localeCompare(b.skill_id)).slice(0, request.limit); } } + + +/** Rank an already-authorized tool catalogue locally; never request embeddings. */ +export function rankToolDefinitions(definitions, query) { + const words = text => new Set(text.toLowerCase().match(/[\p{L}\p{N}]+/gu) ?? []); + const tokens = words(query); + const scored = definitions.map(tool => ({ tool, score: [["name", 3], ["title", 2], ["description", 1]] + .reduce((sum, [field, weight]) => sum + weight * [...words(tool[field] ?? "")].filter(term => tokens.has(term)).length, 0) })); + return scored.filter(item => item.score > 0).sort((a, b) => b.score - a.score + || (a.tool.name < b.tool.name ? -1 : a.tool.name > b.tool.name ? 1 : 0)).map(item => item.tool); +}