@anchrd/intel-api 0.2.0

package/dist/tools/tools.js

@@ -0,0 +1,107 @@
+import { IntelError } from "../shared/intel-error/intel-error.js";
+const CallTimeoutMs = 15_000;
+const MaxTools = 1_000;
+const MaxResultBytes = 1_000_000;
+// Refresh slightly early so a call cannot start with a token that expires mid-flight.
+const RefreshWindowMs = 30_000;
+export function createTools(deps) {
+    function portal() {
+        if (!deps.portalUrl || !deps.sourceAllowed(deps.portalUrl)) {
+            throw new IntelError(503, "portal_not_configured", "No MCP portal is configured for this deployment");
+        }
+        return deps.portalUrl;
+    }
+    // Authorization for tools lives entirely in the portal, so "may this user act" reduces to "does
+    // this user have a usable portal token".
+    async function accessToken(actor) {
+        const stored = await deps.tokens.read(actor.id);
+        if (!stored) {
+            throw new IntelError(401, "portal_not_connected", "Connect the MCP portal to use tools");
+        }
+        if (stored.expiresAt > deps.now().getTime() + RefreshWindowMs)
+            return stored.accessToken;
+        const refreshed = stored.refreshToken ? await deps.refresh(stored) : null;
+        if (!refreshed) {
+            // A token that cannot be renewed is dropped: leaving it would keep failing every call with a
+            // stale credential instead of prompting a reconnect.
+            await deps.tokens.clear(actor.id);
+            throw new IntelError(401, "portal_reconnect_required", "Reconnect the MCP portal to continue");
+        }
+        await deps.tokens.write(actor.id, refreshed);
+        return refreshed.accessToken;
+    }
+    // One live tools/list is both the catalog and the authorization answer: the portal only returns
+    // what this user may reach. Nothing here is cached as a permission.
+    async function capabilities(actor) {
+        const token = await accessToken(actor);
+        const remote = await deps.remote.list(portal(), token, AbortSignal.timeout(CallTimeoutMs));
+        if (remote.length > MaxTools) {
+            throw new IntelError(502, "tool_catalog_too_large", "The portal returned too many tools");
+        }
+        const items = [];
+        for (const tool of remote) {
+            items.push({
+                ...tool,
+                fingerprint: await deps.fingerprint({
+                    name: tool.name,
+                    inputSchema: tool.inputSchema,
+                    outputSchema: tool.outputSchema,
+                    annotations: tool.annotations,
+                }),
+            });
+        }
+        return items;
+    }
+    async function requireCapability(actor, name) {
+        const found = (await capabilities(actor)).find((capability) => capability.name === name);
+        if (!found) {
+            throw new IntelError(404, "tool_not_available", `Tool ${name} is not available to you`);
+        }
+        return found;
+    }
+    async function call(actor, input) {
+        if (!actor.canExecute) {
+            throw new IntelError(403, "tool_execute_forbidden", "Tool execution permission is required");
+        }
+        const capability = await requireCapability(actor, input.name);
+        const validation = deps.validate(capability.inputSchema, input.arguments);
+        if (!validation.valid) {
+            throw new IntelError(400, "tool_arguments_invalid", validation.detail ?? "Invalid arguments");
+        }
+        const result = await deps.remote.call({
+            url: portal(),
+            accessToken: await accessToken(actor),
+            name: capability.name,
+            arguments: input.arguments,
+            signal: AbortSignal.timeout(CallTimeoutMs),
+        });
+        if (new TextEncoder().encode(JSON.stringify(result)).byteLength > MaxResultBytes) {
+            throw new IntelError(502, "tool_result_too_large", "Tool result exceeded the Intel limit");
+        }
+        return result;
+    }
+    return {
+        async catalog(actor) {
+            const stored = await deps.tokens.read(actor.id);
+            // An unconnected portal is a normal state, not an error: the UI shows a connect prompt.
+            if (!stored)
+                return { portalConnected: false, items: [] };
+            return { portalConnected: true, items: await capabilities(actor) };
+        },
+        execute: async (actor, input) => await call(actor, input),
+        async test(actor, input) {
+            const capability = await requireCapability(actor, input.name);
+            if (capability.annotations.readOnlyHint !== true ||
+                capability.annotations.destructiveHint === true) {
+                throw new IntelError(409, "tool_test_unsafe", "Only explicitly read-only, non-destructive tools can run in the test surface");
+            }
+            return await call(actor, input);
+        },
+        async unavailable(actor, names) {
+            if (names.length === 0)
+                return [];
+            const available = new Set((await capabilities(actor)).map((capability) => capability.name));
+            return names.filter((name) => !available.has(name));
+        },
+    };
+}

package/dist/tools/tools.types.d.ts

@@ -0,0 +1,56 @@
+import type { ExecuteToolInput, TestToolInput, ToolCapability, ToolCatalog, ToolTestResult } from "@anchrd/intel-contract";
+export interface ToolActor {
+    id: string;
+    email: string;
+    canExecute: boolean;
+}
+export interface PortalToken {
+    accessToken: string;
+    refreshToken: string | null;
+    expiresAt: number;
+    issuer: string;
+    clientId: string;
+    resource: string;
+}
+export interface PortalTokenStore {
+    read(userId: string): Promise<PortalToken | null>;
+    write(userId: string, token: PortalToken): Promise<void>;
+    clear(userId: string): Promise<void>;
+}
+export interface RemoteTool {
+    name: string;
+    title: string | null;
+    description: string | null;
+    inputSchema: Record<string, unknown>;
+    outputSchema: Record<string, unknown> | null;
+    annotations: ToolCapability["annotations"];
+}
+export interface RemoteTools {
+    list(url: string, accessToken: string, signal: AbortSignal): Promise<RemoteTool[]>;
+    call(input: {
+        url: string;
+        accessToken: string;
+        name: string;
+        arguments: Record<string, unknown>;
+        signal: AbortSignal;
+    }): Promise<ToolTestResult>;
+}
+export interface ToolDeps {
+    portalUrl: string | null;
+    remote: RemoteTools;
+    tokens: PortalTokenStore;
+    refresh(token: PortalToken): Promise<PortalToken | null>;
+    now(): Date;
+    fingerprint(value: unknown): Promise<string>;
+    sourceAllowed(url: string): boolean;
+    validate(schema: Record<string, unknown>, value: unknown): {
+        valid: boolean;
+        detail?: string;
+    };
+}
+export interface ToolService {
+    catalog(actor: ToolActor): Promise<ToolCatalog>;
+    execute(actor: ToolActor, input: ExecuteToolInput): Promise<ToolTestResult>;
+    test(actor: ToolActor, input: TestToolInput): Promise<ToolTestResult>;
+    unavailable(actor: ToolActor, names: string[]): Promise<string[]>;
+}

package/dist/tools/tools.types.js

@@ -0,0 +1 @@
+export {};

package/examples/branding/favicon.svg

@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32">
+  <title>Customer Intel</title>
+  <rect width="32" height="32" rx="8" fill="oklch(0.5 0.18 250)"/>
+  <path d="M10 10h12v12H10zM7 14h3m12 0h3M14 7v3m4-3v3M14 22v3m4-3v3" fill="none" stroke="white" stroke-width="2" stroke-linecap="round"/>
+</svg>

package/examples/branding/logo.svg

@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32">
+  <title>Customer Intel</title>
+  <rect width="32" height="32" rx="8" fill="oklch(0.5 0.18 250)"/>
+  <path d="M10 10h12v12H10zM7 14h3m12 0h3M14 7v3m4-3v3M14 22v3m4-3v3" fill="none" stroke="white" stroke-width="2" stroke-linecap="round"/>
+</svg>

package/examples/branding/theme.css

@@ -0,0 +1,16 @@
+:root {
+  --radius: 0.75rem;
+  --primary: oklch(0.5 0.18 250);
+  --primary-foreground: oklch(0.98 0.01 250);
+  --sidebar-primary: oklch(0.5 0.18 250);
+  --sidebar-primary-foreground: oklch(0.98 0.01 250);
+  --ring: oklch(0.62 0.14 250);
+}
+
+.dark {
+  --primary: oklch(0.72 0.14 250);
+  --primary-foreground: oklch(0.16 0.03 250);
+  --sidebar-primary: oklch(0.72 0.14 250);
+  --sidebar-primary-foreground: oklch(0.16 0.03 250);
+  --ring: oklch(0.68 0.13 250);
+}

package/examples/dev.vars.example

@@ -0,0 +1,7 @@
+GATE_URL=http://localhost:8787
+INTEL_URL=http://localhost:8788
+MCP_PORTAL_URL=https://portal.example.com/mcp
+TOOL_SOURCE_ORIGINS=https://portal.example.com
+ALLOW_INSECURE_OAUTH=true
+GATE_SERVICE_KEY=replace-with-local-gate-service-key
+INTEL_SESSION_SECRET=replace-with-at-least-32-random-bytes

package/examples/intel.json

@@ -0,0 +1,9 @@
+{
+  "ui": {
+    "theme": "./branding/theme.css",
+    "logo": "./branding/logo.svg",
+    "favicon": "./branding/favicon.svg",
+    "defaultLanguage": "en",
+    "languages": {}
+  }
+}

package/migrations/0000_intel_foundation.sql

@@ -0,0 +1,203 @@
+PRAGMA foreign_keys = ON;
+
+CREATE TABLE knowledge_nodes (
+  id TEXT PRIMARY KEY NOT NULL,
+  parent_id TEXT REFERENCES knowledge_nodes(id),
+  kind TEXT NOT NULL CHECK (kind IN ('folder', 'document', 'attachment')),
+  title TEXT NOT NULL CHECK (length(title) BETWEEN 1 AND 240),
+  description TEXT CHECK (description IS NULL OR length(description) <= 2000),
+  context_policy TEXT NOT NULL CHECK (context_policy IN ('pinned', 'relevant', 'explicit')),
+  owner_id TEXT NOT NULL,
+  current_version_id TEXT,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL,
+  archived_at TEXT
+);
+
+CREATE INDEX knowledge_nodes_parent_idx ON knowledge_nodes(parent_id, archived_at, title);
+CREATE INDEX knowledge_nodes_owner_idx ON knowledge_nodes(owner_id, archived_at);
+
+CREATE TABLE knowledge_versions (
+  id TEXT PRIMARY KEY NOT NULL,
+  node_id TEXT NOT NULL REFERENCES knowledge_nodes(id),
+  sequence INTEGER NOT NULL CHECK (sequence > 0),
+  content_key TEXT NOT NULL UNIQUE,
+  media_type TEXT NOT NULL,
+  content_hash TEXT NOT NULL CHECK (length(content_hash) = 64),
+  size INTEGER NOT NULL CHECK (size >= 0),
+  created_by TEXT NOT NULL,
+  created_at TEXT NOT NULL,
+  UNIQUE (node_id, sequence)
+);
+
+CREATE INDEX knowledge_versions_node_idx ON knowledge_versions(node_id, sequence DESC);
+
+CREATE TABLE knowledge_links (
+  id TEXT PRIMARY KEY NOT NULL,
+  source_node_id TEXT NOT NULL REFERENCES knowledge_nodes(id) ON DELETE CASCADE,
+  target_node_id TEXT NOT NULL REFERENCES knowledge_nodes(id) ON DELETE CASCADE,
+  relation TEXT NOT NULL CHECK (relation IN ('references', 'related', 'depends_on', 'implements')),
+  label TEXT CHECK (label IS NULL OR length(label) BETWEEN 1 AND 120),
+  created_by TEXT NOT NULL,
+  created_at TEXT NOT NULL,
+  CHECK (source_node_id <> target_node_id),
+  UNIQUE (source_node_id, target_node_id, relation)
+);
+
+CREATE INDEX knowledge_links_source_idx ON knowledge_links(source_node_id, created_at);
+CREATE INDEX knowledge_links_target_idx ON knowledge_links(target_node_id, created_at);
+
+CREATE TABLE knowledge_index_state (
+  version_id TEXT PRIMARY KEY NOT NULL REFERENCES knowledge_versions(id),
+  status TEXT NOT NULL CHECK (status IN ('pending', 'indexed', 'error')),
+  attempt_count INTEGER NOT NULL DEFAULT 0,
+  last_error TEXT,
+  updated_at TEXT NOT NULL
+);
+
+CREATE INDEX knowledge_index_state_status_idx ON knowledge_index_state(status, updated_at);
+
+CREATE TABLE resource_grants (
+  id TEXT PRIMARY KEY NOT NULL,
+  resource_type TEXT NOT NULL CHECK (resource_type IN ('knowledge', 'flow', 'tool-source')),
+  resource_id TEXT NOT NULL,
+  principal_type TEXT NOT NULL CHECK (principal_type IN ('user', 'email', 'organization')),
+  principal_id TEXT NOT NULL,
+  role TEXT NOT NULL CHECK (role IN ('viewer', 'commenter', 'editor', 'manager')),
+  expires_at TEXT,
+  created_by TEXT NOT NULL,
+  created_at TEXT NOT NULL,
+  UNIQUE (resource_type, resource_id, principal_type, principal_id)
+);
+
+CREATE INDEX resource_grants_principal_idx ON resource_grants(
+  principal_type,
+  principal_id,
+  resource_type,
+  expires_at
+);
+
+CREATE TABLE idempotency_keys (
+  actor_id TEXT NOT NULL,
+  operation TEXT NOT NULL,
+  idempotency_key TEXT NOT NULL,
+  resource_id TEXT NOT NULL,
+  created_at TEXT NOT NULL,
+  PRIMARY KEY (actor_id, operation, idempotency_key)
+);
+
+CREATE INDEX idempotency_keys_created_idx ON idempotency_keys(created_at);
+
+CREATE TABLE audit_events (
+  id TEXT PRIMARY KEY NOT NULL,
+  actor_id TEXT NOT NULL,
+  action TEXT NOT NULL,
+  resource_type TEXT NOT NULL,
+  resource_id TEXT NOT NULL,
+  metadata_json TEXT NOT NULL DEFAULT '{}',
+  occurred_at TEXT NOT NULL
+);
+
+CREATE INDEX audit_events_resource_idx ON audit_events(resource_type, resource_id, occurred_at DESC);
+CREATE INDEX audit_events_actor_idx ON audit_events(actor_id, occurred_at DESC);
+
+CREATE TABLE oauth_clients (
+  issuer TEXT NOT NULL,
+  redirect_uri TEXT NOT NULL,
+  client_id TEXT NOT NULL,
+  created_at TEXT NOT NULL,
+  PRIMARY KEY (issuer, redirect_uri)
+);
+
+CREATE TABLE tool_sources (
+  id TEXT PRIMARY KEY NOT NULL,
+  name TEXT NOT NULL,
+  url TEXT NOT NULL UNIQUE,
+  connection_handle TEXT NOT NULL,
+  enabled INTEGER NOT NULL DEFAULT 1 CHECK (enabled IN (0, 1)),
+  created_by TEXT NOT NULL,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL,
+  last_discovered_at TEXT
+);
+
+CREATE TABLE tool_catalog (
+  source_id TEXT NOT NULL REFERENCES tool_sources(id) ON DELETE CASCADE,
+  name TEXT NOT NULL,
+  title TEXT,
+  description TEXT,
+  input_schema_json TEXT NOT NULL,
+  output_schema_json TEXT,
+  annotations_json TEXT NOT NULL,
+  fingerprint TEXT NOT NULL,
+  discovered_at TEXT NOT NULL,
+  PRIMARY KEY (source_id, name)
+);
+
+CREATE INDEX tool_catalog_title_idx ON tool_catalog(source_id, title, name);
+
+CREATE TABLE flows (
+  id TEXT PRIMARY KEY NOT NULL,
+  title TEXT NOT NULL,
+  description TEXT,
+  owner_id TEXT NOT NULL,
+  current_version_id TEXT,
+  published_version_id TEXT,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL,
+  archived_at TEXT
+);
+
+CREATE INDEX flows_owner_idx ON flows(owner_id, archived_at, updated_at DESC);
+
+CREATE TABLE flow_versions (
+  id TEXT PRIMARY KEY NOT NULL,
+  flow_id TEXT NOT NULL REFERENCES flows(id),
+  sequence INTEGER NOT NULL CHECK (sequence > 0),
+  graph_json TEXT NOT NULL,
+  created_by TEXT NOT NULL,
+  created_at TEXT NOT NULL,
+  UNIQUE (flow_id, sequence)
+);
+
+CREATE INDEX flow_versions_flow_idx ON flow_versions(flow_id, sequence DESC);
+
+CREATE TABLE flow_runs (
+  id TEXT PRIMARY KEY NOT NULL,
+  flow_id TEXT NOT NULL REFERENCES flows(id),
+  version_id TEXT NOT NULL REFERENCES flow_versions(id),
+  status TEXT NOT NULL CHECK (status IN ('queued', 'running', 'waiting', 'completed', 'failed', 'cancelled')),
+  current_node_id TEXT,
+  input_json TEXT NOT NULL,
+  output_json TEXT,
+  error TEXT,
+  initiated_by TEXT NOT NULL,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL,
+  completed_at TEXT,
+  transition_id TEXT
+);
+
+CREATE INDEX flow_runs_flow_idx ON flow_runs(flow_id, created_at DESC);
+CREATE INDEX flow_runs_status_idx ON flow_runs(status, updated_at);
+
+CREATE TABLE flow_run_steps (
+  id TEXT PRIMARY KEY NOT NULL,
+  run_id TEXT NOT NULL REFERENCES flow_runs(id),
+  node_id TEXT NOT NULL,
+  outcome TEXT NOT NULL CHECK (outcome IN ('completed', 'failed')),
+  branch TEXT,
+  output_json TEXT,
+  error TEXT,
+  completed_by TEXT NOT NULL,
+  completed_at TEXT NOT NULL,
+  UNIQUE (run_id, node_id)
+);
+
+CREATE VIRTUAL TABLE knowledge_fts USING fts5(
+  version_id UNINDEXED,
+  node_id UNINDEXED,
+  title,
+  content,
+  tokenize = 'unicode61 remove_diacritics 2'
+);

package/migrations/0001_portal_native_tools.sql

@@ -0,0 +1,21 @@
+-- ADR-0003: the Cloudflare MCP portal owns tool discovery, tool permissions and provider
+-- credentials. Intel no longer registers sources, mirrors a catalog or grants access to tools.
+-- 0.1.x shipped these tables, so they are dropped explicitly rather than removed from 0000.
+
+DROP INDEX IF EXISTS tool_catalog_title_idx;
+DROP TABLE IF EXISTS tool_catalog;
+DROP TABLE IF EXISTS tool_sources;
+
+-- Grants for a resource type that no longer exists would otherwise linger and keep matching the
+-- ACL predicate shape used by knowledge and flows. The CHECK constraint still lists 'tool-source';
+-- rebuilding the table to drop one unused enum value is not worth the migration risk.
+DELETE FROM resource_grants WHERE resource_type = 'tool-source';
+
+-- The only tool-related secret Intel stores: the per-user access token for its own portal
+-- endpoint, sealed with the INTEL_SESSION_SECRET-derived key. No provider credential reaches D1.
+CREATE TABLE portal_tokens (
+  user_id TEXT PRIMARY KEY NOT NULL,
+  sealed TEXT NOT NULL,
+  expires_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL
+);

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@anchrd/intel-api",
+  "version": "0.2.0",
+  "type": "module",
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/anchrd/intel.git",
+    "directory": "packages/api"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "intel": "bin/intel.mjs"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/intel/intel.d.ts",
+      "default": "./dist/intel/intel.js"
+    },
+    "./cloudflare": {
+      "types": "./dist/adapters/cloudflare/cloudflare.d.ts",
+      "default": "./dist/adapters/cloudflare/cloudflare.js"
+    },
+    "./cloudflare-workflow": {
+      "types": "./dist/adapters/cloudflare/cloudflare-flow-workflow.d.ts",
+      "default": "./dist/adapters/cloudflare/cloudflare-flow-workflow.js"
+    }
+  },
+  "files": [
+    "bin",
+    "dist",
+    "examples",
+    "migrations"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && node ../../scripts/pack/fix-dts.mjs",
+    "prepack": "bun run build && node ../../scripts/pack/to-dist-manifest.mjs",
+    "postpack": "node ../../scripts/pack/restore-manifest.mjs",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@anchrd/gate-sdk": "^0.7.0",
+    "@anchrd/intel-contract": "^0.2.0",
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "ajv": "^8.20.0",
+    "hono": "^4.12.32",
+    "openid-client": "^6.8.4",
+    "ulid": "^3.0.2",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@cloudflare/vitest-pool-workers": "^0.19.0",
+    "vitest": "^4.1.10",
+    "wrangler": "^4.115.0"
+  },
+  "main": "./dist/intel/intel.js",
+  "module": "./dist/intel/intel.js",
+  "types": "./dist/intel/intel.d.ts"
+}