@anchrd/intel-api 0.2.0

package/dist/http/http.d.ts

@@ -0,0 +1,8 @@
+import type { Authorized } from "@anchrd/gate-sdk";
+import { Hono } from "hono";
+import type { HttpDeps } from "./http.types.js";
+export declare function createHttp(deps: HttpDeps): Hono<{
+    Variables: {
+        authorization: Authorized;
+    };
+}, import("hono/types").BlankSchema, "/">;

package/dist/http/http.js

@@ -0,0 +1,286 @@
+import { ArchiveKnowledgeNodeInput, CompleteFlowRunStepInput, CreateFlowInput, CreateKnowledgeLinkInput, CreateKnowledgeNodeInput, DeleteKnowledgeLinkInput, ExecuteToolInput, KnowledgeGraphInput, ListKnowledgeNodesInput, PublishFlowInput, RevokeFlowGrantInput, RevokeKnowledgeGrantInput, SaveFlowVersionInput, SaveKnowledgeAttachmentInput, SaveKnowledgeVersionInput, SearchKnowledgeInput, ShareFlowInput, ShareKnowledgeInput, StartFlowRunInput, TestToolInput, UpdateKnowledgeNodeInput, } from "@anchrd/intel-contract";
+import { Hono } from "hono";
+import { z } from "zod";
+import { authorizeBearer, bearer } from "../shared/gate-authorization/gate-authorization.js";
+import { IntelError } from "../shared/intel-error/intel-error.js";
+import { problemDetails as problem } from "../shared/problem-details/problem-details.js";
+function asActor(authorization) {
+    return {
+        id: authorization.identity.id,
+        email: authorization.identity.email,
+        canReindex: authorization.can("intel", "admin"),
+    };
+}
+function asToolActor(authorization) {
+    return {
+        id: authorization.identity.id,
+        email: authorization.identity.email,
+        canExecute: authorization.can("tools", "execute"),
+    };
+}
+// RFC 5987 ext-value: encodeURIComponent leaves ' * ! ( ) unescaped, and a bare apostrophe is a
+// delimiter that would make the header ambiguous. The ASCII filename stays as a fallback.
+function contentDisposition(title) {
+    const encoded = encodeURIComponent(title).replace(/['()*!]/g, (character) => `%${character.charCodeAt(0).toString(16).toUpperCase()}`);
+    const ascii = title.replace(/[^\x20-\x7e]/g, "_").replace(/["\\]/g, "_");
+    return `attachment; filename="${ascii}"; filename*=UTF-8''${encoded}`;
+}
+function asFlowActor(authorization) {
+    return {
+        id: authorization.identity.id,
+        email: authorization.identity.email,
+        canRun: authorization.can("flows", "run"),
+        canApprove: authorization.can("flows", "approve"),
+    };
+}
+export function createHttp(deps) {
+    const app = new Hono();
+    async function authenticated(headers) {
+        const token = bearer(headers) ?? (await deps.auth?.resolve(headers))?.bearer ?? null;
+        return token ? await authorizeBearer(deps.gate, token, deps.resource) : null;
+    }
+    app.onError((error, context) => {
+        if (error instanceof IntelError) {
+            return context.json(problem(error.status, error.code, error.message), error.status);
+        }
+        if (error instanceof z.ZodError) {
+            return context.json(problem(400, "invalid_request", "Request validation failed", z.prettifyError(error)), 400);
+        }
+        return context.json(problem(500, "internal_error", "Internal server error"), 500);
+    });
+    app.use("*", async (context, next) => {
+        const authorization = await authenticated(context.req.raw.headers);
+        if (!authorization) {
+            context.header("WWW-Authenticate", `Bearer resource_metadata="${deps.resourceMetadataUrl}"`);
+            return context.json(problem(401, "authentication_required", "Authentication required"), 401);
+        }
+        context.set("authorization", authorization);
+        await next();
+    });
+    function requireCapability(context, handle, fn) {
+        const authorization = context.get("authorization");
+        if (!authorization.can(handle, fn)) {
+            throw new IntelError(403, "permission_required", "Permission required");
+        }
+        return authorization;
+    }
+    app.get("/knowledge", async (context) => {
+        const auth = requireCapability(context, "knowledge", "read");
+        const url = new URL(context.req.url);
+        const unknownQuery = [];
+        url.searchParams.forEach((_value, key) => {
+            if (key !== "parentId" && key !== "includeArchived")
+                unknownQuery.push(key);
+        });
+        if (unknownQuery.length) {
+            throw new IntelError(400, "invalid_request", `Unknown query parameters: ${unknownQuery.join(", ")}`);
+        }
+        const input = ListKnowledgeNodesInput.parse({
+            parentId: url.searchParams.get("parentId"),
+            includeArchived: url.searchParams.get("includeArchived") === "true",
+        });
+        return context.json(await deps.knowledge.list(asActor(auth), input));
+    });
+    app.get("/knowledge/graph", async (context) => {
+        const auth = requireCapability(context, "knowledge", "read");
+        const url = new URL(context.req.url);
+        const input = KnowledgeGraphInput.parse({
+            limit: url.searchParams.has("limit") ? Number(url.searchParams.get("limit")) : undefined,
+        });
+        return context.json(await deps.knowledge.graph(asActor(auth), input));
+    });
+    app.get("/knowledge/:nodeId", async (context) => {
+        const auth = requireCapability(context, "knowledge", "read");
+        return context.json(await deps.knowledge.get(asActor(auth), context.req.param("nodeId")));
+    });
+    app.get("/knowledge/:nodeId/versions", async (context) => {
+        const auth = requireCapability(context, "knowledge", "read");
+        return context.json(await deps.knowledge.listVersions(asActor(auth), context.req.param("nodeId")));
+    });
+    app.get("/knowledge/:nodeId/attachment", async (context) => {
+        const auth = requireCapability(context, "knowledge", "read");
+        const { attachment, body } = await deps.knowledge.readAttachment(asActor(auth), context.req.param("nodeId"));
+        return new Response(body, {
+            headers: {
+                "cache-control": "private, no-store",
+                "content-disposition": contentDisposition(attachment.node.title),
+                "content-type": attachment.version.mediaType,
+                "x-content-type-options": "nosniff",
+            },
+        });
+    });
+    app.get("/knowledge/:nodeId/links", async (context) => {
+        const auth = requireCapability(context, "knowledge", "read");
+        return context.json(await deps.knowledge.listLinks(asActor(auth), context.req.param("nodeId")));
+    });
+    app.post("/knowledge/search", async (context) => {
+        const auth = requireCapability(context, "knowledge", "read");
+        const input = SearchKnowledgeInput.parse(await context.req.json().catch(() => null));
+        return context.json(await deps.knowledge.search(asActor(auth), input));
+    });
+    app.post("/search/reindex", async (context) => {
+        const auth = requireCapability(context, "intel", "admin");
+        z.strictObject({}).parse(await context.req.json().catch(() => null));
+        return context.json(await deps.knowledge.reindex(asActor(auth)), 202);
+    });
+    app.post("/knowledge", async (context) => {
+        const auth = requireCapability(context, "knowledge", "create");
+        const input = CreateKnowledgeNodeInput.parse(await context.req.json().catch(() => null));
+        return context.json(await deps.knowledge.create(asActor(auth), input), 201);
+    });
+    app.post("/knowledge/:nodeId/versions", async (context) => {
+        const auth = requireCapability(context, "knowledge", "write");
+        const input = SaveKnowledgeVersionInput.parse(await context.req.json().catch(() => null));
+        if (input.nodeId !== context.req.param("nodeId")) {
+            throw new IntelError(400, "node_id_mismatch", "Path and body node IDs differ");
+        }
+        return context.json(await deps.knowledge.save(asActor(auth), input), 201);
+    });
+    app.post("/knowledge/:nodeId/attachment", async (context) => {
+        const auth = requireCapability(context, "knowledge", "write");
+        const input = SaveKnowledgeAttachmentInput.parse(await context.req.json().catch(() => null));
+        if (input.nodeId !== context.req.param("nodeId")) {
+            throw new IntelError(400, "node_id_mismatch", "Path and body node IDs differ");
+        }
+        return context.json(await deps.knowledge.saveAttachment(asActor(auth), input), 201);
+    });
+    app.patch("/knowledge/:nodeId", async (context) => {
+        const auth = requireCapability(context, "knowledge", "write");
+        const input = UpdateKnowledgeNodeInput.parse(await context.req.json().catch(() => null));
+        if (input.nodeId !== context.req.param("nodeId")) {
+            throw new IntelError(400, "node_id_mismatch", "Path and body node IDs differ");
+        }
+        return context.json(await deps.knowledge.update(asActor(auth), input));
+    });
+    app.post("/knowledge/:nodeId/archive", async (context) => {
+        const auth = requireCapability(context, "knowledge", "write");
+        const input = ArchiveKnowledgeNodeInput.parse(await context.req.json().catch(() => null));
+        if (input.nodeId !== context.req.param("nodeId")) {
+            throw new IntelError(400, "node_id_mismatch", "Path and body node IDs differ");
+        }
+        return context.json(await deps.knowledge.archive(asActor(auth), input));
+    });
+    app.post("/knowledge/:nodeId/links", async (context) => {
+        const auth = requireCapability(context, "knowledge", "write");
+        const input = CreateKnowledgeLinkInput.parse(await context.req.json().catch(() => null));
+        if (input.sourceNodeId !== context.req.param("nodeId")) {
+            throw new IntelError(400, "node_id_mismatch", "Path and body source node IDs differ");
+        }
+        return context.json(await deps.knowledge.createLink(asActor(auth), input), 201);
+    });
+    app.post("/knowledge/:nodeId/links/:linkId/revoke", async (context) => {
+        const auth = requireCapability(context, "knowledge", "write");
+        const input = DeleteKnowledgeLinkInput.parse(await context.req.json().catch(() => null));
+        if (input.sourceNodeId !== context.req.param("nodeId") ||
+            input.linkId !== context.req.param("linkId")) {
+            throw new IntelError(400, "link_id_mismatch", "Path and body Knowledge link IDs differ");
+        }
+        return context.json(await deps.knowledge.deleteLink(asActor(auth), input));
+    });
+    app.get("/knowledge/:nodeId/grants", async (context) => {
+        const auth = requireCapability(context, "knowledge", "share");
+        return context.json(await deps.knowledge.listGrants(asActor(auth), context.req.param("nodeId")));
+    });
+    app.post("/knowledge/:nodeId/grants", async (context) => {
+        const auth = requireCapability(context, "knowledge", "share");
+        const input = ShareKnowledgeInput.parse(await context.req.json().catch(() => null));
+        if (input.resourceId !== context.req.param("nodeId")) {
+            throw new IntelError(400, "node_id_mismatch", "Path and body resource IDs differ");
+        }
+        return context.json(await deps.knowledge.share(asActor(auth), input), 201);
+    });
+    app.post("/knowledge/:nodeId/grants/:grantId/revoke", async (context) => {
+        const auth = requireCapability(context, "knowledge", "share");
+        const input = RevokeKnowledgeGrantInput.parse(await context.req.json().catch(() => null));
+        if (input.resourceId !== context.req.param("nodeId") ||
+            input.grantId !== context.req.param("grantId")) {
+            throw new IntelError(400, "grant_id_mismatch", "Path and body grant IDs differ");
+        }
+        return context.json(await deps.knowledge.revokeGrant(asActor(auth), input));
+    });
+    app.get("/flows", async (context) => {
+        const auth = requireCapability(context, "flows", "read");
+        return context.json(await deps.flows.list(asFlowActor(auth)));
+    });
+    app.get("/flows/:flowId", async (context) => {
+        const auth = requireCapability(context, "flows", "read");
+        return context.json(await deps.flows.get(asFlowActor(auth), context.req.param("flowId")));
+    });
+    app.get("/flows/:flowId/grants", async (context) => {
+        const auth = requireCapability(context, "flows", "share");
+        return context.json(await deps.flows.listGrants(asFlowActor(auth), context.req.param("flowId")));
+    });
+    app.post("/flows/:flowId/grants", async (context) => {
+        const auth = requireCapability(context, "flows", "share");
+        const input = ShareFlowInput.parse(await context.req.json().catch(() => null));
+        if (input.resourceId !== context.req.param("flowId")) {
+            throw new IntelError(400, "flow_id_mismatch", "Path and body flow IDs differ");
+        }
+        return context.json(await deps.flows.share(asFlowActor(auth), input), 201);
+    });
+    app.post("/flows/:flowId/grants/:grantId/revoke", async (context) => {
+        const auth = requireCapability(context, "flows", "share");
+        const input = RevokeFlowGrantInput.parse(await context.req.json().catch(() => null));
+        if (input.resourceId !== context.req.param("flowId") ||
+            input.grantId !== context.req.param("grantId")) {
+            throw new IntelError(400, "grant_id_mismatch", "Path and body grant IDs differ");
+        }
+        return context.json(await deps.flows.revokeGrant(asFlowActor(auth), input));
+    });
+    app.post("/flows", async (context) => {
+        const auth = requireCapability(context, "flows", "create");
+        const input = CreateFlowInput.parse(await context.req.json().catch(() => null));
+        return context.json(await deps.flows.create(asFlowActor(auth), input), 201);
+    });
+    app.post("/flows/:flowId/versions", async (context) => {
+        const auth = requireCapability(context, "flows", "write");
+        const input = SaveFlowVersionInput.parse(await context.req.json().catch(() => null));
+        if (input.flowId !== context.req.param("flowId")) {
+            throw new IntelError(400, "flow_id_mismatch", "Path and body flow IDs differ");
+        }
+        return context.json(await deps.flows.save(asFlowActor(auth), input), 201);
+    });
+    app.post("/flows/:flowId/publish", async (context) => {
+        const auth = requireCapability(context, "flows", "publish");
+        const input = PublishFlowInput.parse(await context.req.json().catch(() => null));
+        if (input.flowId !== context.req.param("flowId")) {
+            throw new IntelError(400, "flow_id_mismatch", "Path and body flow IDs differ");
+        }
+        return context.json(await deps.flows.publish(asFlowActor(auth), input));
+    });
+    app.post("/flows/:flowId/runs", async (context) => {
+        const auth = requireCapability(context, "flows", "run");
+        const input = StartFlowRunInput.parse(await context.req.json().catch(() => null));
+        if (input.flowId !== context.req.param("flowId")) {
+            throw new IntelError(400, "flow_id_mismatch", "Path and body flow IDs differ");
+        }
+        return context.json(await deps.flows.start(asFlowActor(auth), input), 201);
+    });
+    app.get("/flow-runs/:runId", async (context) => {
+        const auth = requireCapability(context, "flows", "read");
+        return context.json(await deps.flows.getRun(asFlowActor(auth), context.req.param("runId")));
+    });
+    app.post("/flow-runs/:runId/complete", async (context) => {
+        const auth = requireCapability(context, "flows", "run");
+        const input = CompleteFlowRunStepInput.parse(await context.req.json().catch(() => null));
+        if (input.runId !== context.req.param("runId")) {
+            throw new IntelError(400, "run_id_mismatch", "Path and body run IDs differ");
+        }
+        return context.json(await deps.flows.completeStep(asFlowActor(auth), input));
+    });
+    app.get("/tools", async (context) => {
+        const auth = requireCapability(context, "tools", "read");
+        return context.json(await deps.tools.catalog(asToolActor(auth)));
+    });
+    app.post("/tools/test", async (context) => {
+        const auth = requireCapability(context, "tools", "test");
+        const input = TestToolInput.parse(await context.req.json().catch(() => null));
+        return context.json(await deps.tools.test(asToolActor(auth), input));
+    });
+    app.post("/tools/execute", async (context) => {
+        const auth = requireCapability(context, "tools", "execute");
+        const input = ExecuteToolInput.parse(await context.req.json().catch(() => null));
+        return context.json(await deps.tools.execute(asToolActor(auth), input));
+    });
+    return app;
+}

package/dist/http/http.types.d.ts

@@ -0,0 +1,14 @@
+import type { GateClient } from "@anchrd/gate-sdk";
+import type { BrowserAuth } from "../auth/auth.types.js";
+import type { FlowService } from "../flows/flows.types.js";
+import type { KnowledgeService } from "../knowledge/knowledge.types.js";
+import type { ToolService } from "../tools/tools.types.js";
+export interface HttpDeps {
+    gate: Pick<GateClient, "authorize">;
+    knowledge: KnowledgeService;
+    flows: FlowService;
+    tools: ToolService;
+    resource: string;
+    resourceMetadataUrl: string;
+    auth?: Pick<BrowserAuth, "resolve">;
+}

package/dist/http/http.types.js

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

package/dist/indexing/indexing.d.ts

@@ -0,0 +1,6 @@
+import type { IndexingDeps } from "./indexing.types.js";
+export declare class PermanentIndexingError extends Error {
+}
+export declare function createIndexing(deps: IndexingDeps): {
+    index(versionId: string): Promise<void>;
+};

package/dist/indexing/indexing.js

@@ -0,0 +1,48 @@
+import { BlockNoteDocument, BlockNoteMediaType } from "@anchrd/intel-contract";
+export class PermanentIndexingError extends Error {
+}
+function indexText(mediaType, content) {
+    if (mediaType !== BlockNoteMediaType)
+        return content;
+    try {
+        return BlockNoteDocument.parse(JSON.parse(content)).markdown;
+    }
+    catch (error) {
+        // Immutable content never becomes parsable on a retry, so treating this as transient would
+        // requeue the version until the queue gives up and would bury the real cause.
+        throw new PermanentIndexingError(`Knowledge version content is not a valid BlockNote document: ${error instanceof Error ? error.message : "unknown parse failure"}`);
+    }
+}
+export function createIndexing(deps) {
+    return {
+        async index(versionId) {
+            const target = await deps.repository.getTarget(versionId);
+            if (!target)
+                return;
+            const canonical = target.kind === "attachment"
+                ? await deps.content.getBytes(target.contentKey)
+                : await deps.content.get(target.contentKey);
+            if (canonical === null) {
+                await deps.repository.markError(versionId, "content_missing", deps.now().toISOString());
+                throw new Error("Knowledge version content is missing");
+            }
+            try {
+                const text = typeof canonical === "string"
+                    ? indexText(target.mediaType, canonical)
+                    : target.mediaType.startsWith("text/")
+                        ? new TextDecoder().decode(canonical)
+                        : await deps.converter?.convert(target.title, target.mediaType, canonical);
+                if (text === undefined) {
+                    throw new PermanentIndexingError(`No document converter is configured for ${target.mediaType}`);
+                }
+                await deps.repository.replace(target, text);
+                await deps.semantic?.replace(target, text);
+                await deps.repository.markIndexed(versionId, deps.now().toISOString());
+            }
+            catch (error) {
+                await deps.repository.markError(versionId, error instanceof Error ? error.message : "indexing_failed", deps.now().toISOString());
+                throw error;
+            }
+        },
+    };
+}

package/dist/indexing/indexing.types.d.ts

@@ -0,0 +1,10 @@
+import type { DocumentConverter } from "../adapters/document-converter/document-converter.types.js";
+import type { SemanticIndex } from "../adapters/semantic-index/semantic-index.types.js";
+import type { ContentStore, KnowledgeIndexRepository } from "../knowledge/knowledge.types.js";
+export interface IndexingDeps {
+    repository: KnowledgeIndexRepository;
+    content: ContentStore;
+    semantic?: SemanticIndex | undefined;
+    converter?: DocumentConverter | undefined;
+    now(): Date;
+}

package/dist/indexing/indexing.types.js

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

package/dist/intel/intel.d.ts

@@ -0,0 +1,3 @@
+import { Hono } from "hono";
+import type { IntelDeps } from "./intel.types.js";
+export declare function createIntel(deps: IntelDeps): Hono<import("hono/types").BlankEnv, import("hono/types").BlankSchema, "/">;

package/dist/intel/intel.js

@@ -0,0 +1,77 @@
+import { Hono } from "hono";
+import { createHttp } from "../http/http.js";
+import { handleMcp } from "../mcp/mcp.js";
+import { authorize, authorizeBearer } from "../shared/gate-authorization/gate-authorization.js";
+import { IntelError } from "../shared/intel-error/intel-error.js";
+import { problemDetails } from "../shared/problem-details/problem-details.js";
+export function createIntel(deps) {
+    const baseUrl = deps.baseUrl.replace(/\/+$/, "");
+    const resource = `${baseUrl}/mcp`;
+    const resourceMetadataUrl = `${baseUrl}/.well-known/oauth-protected-resource`;
+    const app = new Hono();
+    app.onError((error, context) => {
+        if (error instanceof IntelError) {
+            return context.json(problemDetails(error.status, error.code, error.message), error.status);
+        }
+        return context.json(problemDetails(500, "internal_error", "Internal server error"), 500);
+    });
+    app.get("/health", (context) => context.json({ status: "ok" }));
+    app.get("/.well-known/oauth-protected-resource", (context) => context.json({
+        resource,
+        authorization_servers: [deps.gateUrl.replace(/\/+$/, "")],
+        bearer_methods_supported: ["header"],
+    }));
+    const browserAuth = deps.auth;
+    if (browserAuth) {
+        app.get("/auth/login", async (context) => await browserAuth.login(new URL(context.req.url)));
+        // One connect route for the one portal: there are no per-source connections any more.
+        app.get("/auth/connect", async (context) => {
+            const connectReturnTo = encodeURIComponent("/auth/connect?returnTo=/tools");
+            const session = await browserAuth.resolve(context.req.raw.headers);
+            if (!session) {
+                return context.redirect(`/auth/login?returnTo=${connectReturnTo}`);
+            }
+            const authorization = await authorizeBearer(deps.gate, session.bearer, resource);
+            if (!authorization) {
+                return context.redirect(`/auth/login?returnTo=${connectReturnTo}`);
+            }
+            if (!authorization.can("tools", "read")) {
+                return context.redirect("/tools?connectError=permission_required");
+            }
+            try {
+                return await browserAuth.connect(new URL(context.req.url), context.req.raw.headers, authorization.identity.id);
+            }
+            catch (error) {
+                if (error instanceof IntelError) {
+                    return context.redirect(`/tools?connectError=${encodeURIComponent(error.code)}`);
+                }
+                throw error;
+            }
+        });
+        app.get("/auth/callback", async (context) => await browserAuth.callback(new URL(context.req.url), context.req.raw.headers));
+        app.post("/auth/logout", () => browserAuth.logout());
+    }
+    app.route("/api/v1", createHttp({
+        gate: deps.gate,
+        knowledge: deps.knowledge,
+        flows: deps.flows,
+        tools: deps.tools,
+        resource,
+        resourceMetadataUrl,
+        ...(deps.auth ? { auth: deps.auth } : {}),
+    }));
+    app.all("/mcp", async (context) => {
+        const authorization = await authorize(deps.gate, context.req.raw.headers, resource);
+        if (!authorization) {
+            context.header("WWW-Authenticate", `Bearer resource_metadata="${resourceMetadataUrl}"`);
+            return context.json({ jsonrpc: "2.0", id: null, error: { code: -32003, message: "authentication required" } }, 401);
+        }
+        return await handleMcp(context.req.raw, {
+            authorization,
+            flows: deps.flows,
+            knowledge: deps.knowledge,
+            tools: deps.tools,
+        });
+    });
+    return app;
+}

package/dist/intel/intel.types.d.ts

@@ -0,0 +1,14 @@
+import type { GateClient } from "@anchrd/gate-sdk";
+import type { BrowserAuth } from "../auth/auth.types.js";
+import type { FlowService } from "../flows/flows.types.js";
+import type { KnowledgeService } from "../knowledge/knowledge.types.js";
+import type { ToolService } from "../tools/tools.types.js";
+export interface IntelDeps {
+    baseUrl: string;
+    gateUrl: string;
+    gate: Pick<GateClient, "authorize">;
+    knowledge: KnowledgeService;
+    flows: FlowService;
+    tools: ToolService;
+    auth?: BrowserAuth;
+}

package/dist/intel/intel.types.js

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

package/dist/knowledge/knowledge.d.ts

@@ -0,0 +1,2 @@
+import type { KnowledgeDeps, KnowledgeService } from "./knowledge.types.js";
+export declare function createKnowledge(deps: KnowledgeDeps): KnowledgeService;