@gmickel/gno 1.27.1 → 1.29.0

package/src/mcp/http-egress.ts

@@ -0,0 +1,220 @@
+/** Per-request egress authorization for the resident HTTP MCP boundary. */
+
+import type { Collection } from "../config/types";
+import type {
+  EgressContentClass,
+  EgressDestinationZone,
+} from "../core/egress-policy";
+
+import { parseUri } from "../app/constants";
+import {
+  collectionEgressStates,
+  EGRESS_DENIED_MESSAGE,
+  EgressDeniedError,
+} from "../core/egress-enforcement";
+import { evaluateEgressPolicy } from "../core/egress-policy";
+
+export const MCP_HTTP_EGRESS_TOOLS = {
+  gno_add_collection: "metadata",
+  gno_ask: "capsule",
+  gno_backlinks: "metadata",
+  gno_capture: "metadata",
+  gno_changes: "metadata",
+  gno_clear_collection_embeddings: "metadata",
+  gno_context: "capsule",
+  gno_context_verify: "capsule",
+  gno_create_folder: "metadata",
+  gno_diff: "metadata",
+  gno_duplicate_note: "metadata",
+  gno_embed: "metadata",
+  gno_egress_audit_delete: "audit_log",
+  gno_egress_audit_list: "audit_log",
+  gno_egress_audit_purge: "audit_log",
+  gno_egress_audit_show: "audit_log",
+  gno_egress_audit_status: "audit_log",
+  gno_egress_check: "audit_log",
+  gno_egress_policy_get: "metadata",
+  gno_egress_policy_set: "metadata",
+  gno_get: "source",
+  gno_graph: "metadata",
+  gno_graph_neighbors: "metadata",
+  gno_graph_path: "metadata",
+  gno_graph_query: "metadata",
+  gno_impact: "metadata",
+  gno_index: "metadata",
+  gno_job_status: "metadata",
+  gno_links: "metadata",
+  gno_list_jobs: "metadata",
+  gno_list_tags: "metadata",
+  gno_move_note: "metadata",
+  gno_multi_get: "source",
+  gno_query: "snippet",
+  gno_query_diagnose: "metadata",
+  gno_remove_collection: "metadata",
+  gno_rename_note: "metadata",
+  gno_search: "snippet",
+  gno_similar: "snippet",
+  gno_status: "metadata",
+  gno_sync: "metadata",
+  gno_trace_delete: "retrieval_trace",
+  gno_trace_export: "retrieval_trace",
+  gno_trace_label: "retrieval_trace",
+  gno_trace_list: "retrieval_trace",
+  gno_trace_purge: "retrieval_trace",
+  gno_trace_show: "retrieval_trace",
+  gno_vsearch: "snippet",
+} as const satisfies Record<string, EgressContentClass>;
+
+export const MCP_HTTP_EGRESS_METHODS = {
+  "resources/list": "metadata",
+  "resources/read": "source",
+  "resources/templates/list": "metadata",
+} as const satisfies Record<string, EgressContentClass>;
+
+export interface HttpMcpEgressContext {
+  authenticated: boolean;
+  destinationZone: EgressDestinationZone;
+  operationAuthorized: boolean;
+}
+
+interface JsonRpcMessage {
+  id?: unknown;
+  method?: unknown;
+  params?: unknown;
+}
+
+export class HttpMcpEgressDeniedError extends EgressDeniedError {
+  readonly requestId: unknown;
+
+  constructor(error: EgressDeniedError, requestId: unknown) {
+    super(error.decision);
+    this.name = "HttpMcpEgressDeniedError";
+    this.requestId = requestId;
+  }
+}
+
+const SYSTEM_EGRESS_STATE = {
+  collection: "system",
+  policy: "local_only",
+  source: "config_default",
+} as const;
+
+const asRecord = (value: unknown): Record<string, unknown> | null =>
+  typeof value === "object" && value !== null
+    ? (value as Record<string, unknown>)
+    : null;
+
+const collectionFromRef = (value: unknown): string | null => {
+  if (typeof value !== "string") return null;
+  const parsed = parseUri(value);
+  if (parsed) return parsed.collection;
+  const slash = value.indexOf("/");
+  if (slash <= 0 || value.startsWith("#")) return null;
+  return value.slice(0, slash).trim().toLowerCase() || null;
+};
+
+const requestedCollections = (
+  params: unknown,
+  collections: readonly Collection[]
+): string[] => {
+  const record = asRecord(params);
+  const args = asRecord(record?.arguments ?? params);
+  if (!args) return collections.map(({ name }) => name);
+
+  const names = new Set<string>();
+  const direct = args.collection;
+  if (typeof direct === "string") names.add(direct.trim().toLowerCase());
+  for (const key of ["ref", "target", "from", "to", "root", "uri"]) {
+    const collection = collectionFromRef(args[key]);
+    if (collection) names.add(collection);
+  }
+  if (Array.isArray(args.refs)) {
+    for (const ref of args.refs) {
+      const collection = collectionFromRef(ref);
+      if (collection) names.add(collection);
+    }
+  }
+  return names.size > 0 ? [...names] : collections.map(({ name }) => name);
+};
+
+const enforceMessage = (
+  message: JsonRpcMessage,
+  collections: readonly Collection[],
+  context: HttpMcpEgressContext
+): void => {
+  let contentClass: EgressContentClass | undefined;
+  if (message.method === "tools/call") {
+    const params = asRecord(message.params);
+    const name = params?.name;
+    if (typeof name !== "string" || !(name in MCP_HTTP_EGRESS_TOOLS)) return;
+    // Trace export is authorized inside RetrievalTraceManagementService after
+    // exact trace IDs resolve to their immutable collection lineage.
+    if (name === "gno_trace_export") return;
+    contentClass =
+      MCP_HTTP_EGRESS_TOOLS[name as keyof typeof MCP_HTTP_EGRESS_TOOLS];
+  } else if (
+    typeof message.method === "string" &&
+    message.method in MCP_HTTP_EGRESS_METHODS
+  ) {
+    contentClass =
+      MCP_HTTP_EGRESS_METHODS[
+        message.method as keyof typeof MCP_HTTP_EGRESS_METHODS
+      ];
+  } else {
+    return;
+  }
+
+  const names = requestedCollections(message.params, collections);
+  const scoped = collectionEgressStates(collections, names);
+  const decision = evaluateEgressPolicy({
+    collections: scoped.length > 0 ? scoped : [SYSTEM_EGRESS_STATE],
+    action: "serve",
+    destination: { zone: context.destinationZone },
+    caller: {
+      authenticated: context.authenticated,
+      operationAuthorized: context.operationAuthorized,
+    },
+    contentClass,
+  });
+  if (!decision.allowed) {
+    throw new HttpMcpEgressDeniedError(
+      new EgressDeniedError(decision),
+      message.id
+    );
+  }
+};
+
+export const enforceHttpMcpEgress = (
+  payload: unknown,
+  collections: readonly Collection[],
+  context: HttpMcpEgressContext
+): void => {
+  const messages = Array.isArray(payload) ? payload : [payload];
+  for (const value of messages) {
+    const message = asRecord(value);
+    if (message) enforceMessage(message, collections, context);
+  }
+};
+
+export const httpMcpEgressDeniedResponse = (
+  error: EgressDeniedError,
+  payload: unknown
+): Response => {
+  const first = Array.isArray(payload) ? payload[0] : payload;
+  const id =
+    error instanceof HttpMcpEgressDeniedError
+      ? (error.requestId ?? null)
+      : (asRecord(first)?.id ?? null);
+  return Response.json(
+    {
+      jsonrpc: "2.0",
+      error: {
+        code: -32_003,
+        message: EGRESS_DENIED_MESSAGE,
+        data: error.toJSON(),
+      },
+      id,
+    },
+    { status: 403 }
+  );
+};

package/src/mcp/http-security.ts

@@ -4,8 +4,13 @@
 import { lstat, open } from "node:fs/promises";
 
 import type { HttpGatewayConfig } from "../config/types";
+import type { DestinationClassification } from "../core/destination-classifier";
 
 import { expandPath } from "../config/paths";
+import {
+  classifyBindDestination,
+  classifyDestination,
+} from "../core/destination-classifier";
 
 export const DEFAULT_HTTP_GATEWAY_HOST = "127.0.0.1";
 export const DEFAULT_HTTP_GATEWAY_PORT = 3000;
@@ -54,7 +59,9 @@ export interface HttpGatewayOverrides {
 }
 
 export interface AuthorizedHttpMcpRequest {
+  authenticated: boolean;
   identity: string;
+  peerClassification: DestinationClassification;
   parsedBody?: unknown;
   request: Request;
 }
@@ -97,29 +104,21 @@ function securityError(status: 401 | 403 | 413 | 429 | 503): Response {
   );
 }
 
-function isLoopbackAddress(address: string): boolean {
-  const normalized = address.toLowerCase();
-  if (normalized === "::1") return true;
-  const mapped = normalized.startsWith("::ffff:")
-    ? normalized.slice("::ffff:".length)
-    : normalized;
-  const octets = mapped.split(".");
-  return (
-    octets.length === 4 &&
-    octets.every((octet) => /^\d{1,3}$/.test(octet)) &&
-    Number(octets[0]) === 127 &&
-    octets.every((octet) => Number(octet) <= 255)
-  );
-}
-
 export function isHttpGatewayLoopbackBind(host: string): boolean {
-  return host === "127.0.0.1" || host === "::1" || host === "[::1]";
+  return classifyBindDestination(host).zone === "loopback";
 }
 
 function defaultAllowedHosts(host: string, port: number): string[] {
-  if (host === "127.0.0.1") return [`127.0.0.1:${port}`, `localhost:${port}`];
-  if (host === "::1" || host === "[::1]") return [`[::1]:${port}`];
-  return [];
+  if (!isHttpGatewayLoopbackBind(host)) return [];
+  const normalized =
+    host.startsWith("[") && host.endsWith("]") ? host.slice(1, -1) : host;
+  const rawAuthority = normalized.includes(":")
+    ? `[${normalized}]:${port}`
+    : `${normalized}:${port}`;
+  const authority = new URL(`http://${rawAuthority}`).host;
+  return normalized === "127.0.0.1"
+    ? [authority, `localhost:${port}`]
+    : [authority];
 }
 
 function defaultAllowedOrigins(host: string, port: number): string[] {
@@ -370,9 +369,13 @@ export class HttpMcpSecurity {
   ): Promise<HttpMcpAuthorizationResult> {
     const peer = server.requestIP(request);
     if (!peer) return { ok: false, response: securityError(403) };
+    const peerClassification = classifyDestination({
+      kind: "network",
+      hostname: peer.address,
+    });
     if (
       isHttpGatewayLoopbackBind(this.#config.host) &&
-      !isLoopbackAddress(peer.address)
+      peerClassification.zone !== "loopback"
     )
       return { ok: false, response: securityError(403) };
 
@@ -397,6 +400,7 @@ export class HttpMcpSecurity {
       this.#config.tokenFile !== undefined;
     const tokenState = await this.#refreshTokenState();
     let identity = "loopback";
+    let authenticated = false;
     if (requiresAuth) {
       if (!tokenState) return { ok: false, response: securityError(503) };
       const authorization = request.headers.get("authorization");
@@ -406,6 +410,7 @@ export class HttpMcpSecurity {
       if (!constantTimeEqual(presentedDigest, tokenState.digest))
         return { ok: false, response: securityError(401) };
       identity = tokenState.digest;
+      authenticated = true;
     }
 
     let parsedBody: unknown;
@@ -435,7 +440,13 @@ export class HttpMcpSecurity {
 
     return {
       ok: true,
-      value: { identity, parsedBody, request: sanitizedRequest },
+      value: {
+        authenticated,
+        identity,
+        peerClassification,
+        parsedBody,
+        request: sanitizedRequest,
+      },
     };
   }
 

package/src/mcp/http-session.ts

@@ -43,6 +43,7 @@ export interface PendingHttpMcpSession {
 }
 
 interface OwnedHttpMcpSession extends HttpMcpSession {
+  invalidated: boolean;
   releaseRuntimeSession(): void;
 }
 
@@ -133,6 +134,10 @@ export class HttpMcpSessionStore {
   finishRequest(session: HttpMcpSession): void {
     session.activeRequests = Math.max(0, session.activeRequests - 1);
     session.lastActivityAt = this.#now();
+    const owned = session as OwnedHttpMcpSession;
+    if (owned.invalidated && owned.activeRequests === 0) {
+      void owned.server.close().catch(() => undefined);
+    }
   }
 
   async createPendingSession(
@@ -168,6 +173,7 @@ export class HttpMcpSessionStore {
           transport,
           lastActivityAt: this.#now(),
           activeRequests: 0,
+          invalidated: false,
           releaseRuntimeSession,
         };
         this.#sessions.set(sessionId, host.session);
@@ -250,14 +256,19 @@ export class HttpMcpSessionStore {
   async closeSessions(): Promise<void> {
     const sessions = [...this.#sessions.values()];
     this.#sessions.clear();
-    for (const session of sessions) session.releaseRuntimeSession();
+    for (const session of sessions) {
+      session.invalidated = true;
+      session.releaseRuntimeSession();
+    }
 
     const pending = [...this.#pending];
     this.#pending.clear();
     for (const host of pending) host.discarded = true;
 
     await Promise.allSettled([
-      ...sessions.map((session) => session.server.close()),
+      ...sessions
+        .filter((session) => session.activeRequests === 0)
+        .map((session) => session.server.close()),
       ...pending.map((host) => host.server.close()),
     ]);
   }

package/src/mcp/http-transport.ts

@@ -2,6 +2,7 @@
 
 import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
 
+import type { DestinationClassification } from "../core/destination-classifier";
 import type { ResidentRequestHandle } from "../serve/resident-runtime";
 import type {
   HttpMcpSession,
@@ -10,6 +11,11 @@ import type {
   PendingHttpMcpSession,
 } from "./http-session";
 
+import { EgressDeniedError } from "../core/egress-enforcement";
+import {
+  enforceHttpMcpEgress,
+  httpMcpEgressDeniedResponse,
+} from "./http-egress";
 import { HttpMcpSessionStore } from "./http-session";
 import { MCP_WRITE_TOOL_NAMES } from "./tools/index";
 
@@ -17,8 +23,12 @@ const DEFAULT_MAX_CONCURRENT_REQUESTS = 64;
 const DEFAULT_MAX_QUEUED_REQUESTS = 0;
 const MCP_HTTP_METHODS = new Set(["DELETE", "GET", "POST"]);
 const MCP_SESSION_HEADER = "mcp-session-id";
+const POLICY_CHANGED_SSE = new TextEncoder().encode(
+  'event: message\ndata: {"jsonrpc":"2.0","error":{"code":-32000,"message":"EGRESS_POLICY_CHANGED: Collection policy changed; retry"},"id":null}\n\n'
+);
 
 export interface HttpMcpTransportRuntime extends HttpMcpSessionRuntime {
+  readonly authorizationEpoch?: string;
   readonly isShuttingDown: boolean;
   admitRequest(signal?: AbortSignal): ResidentRequestHandle | null;
 }
@@ -30,8 +40,10 @@ export interface HttpMcpTransportOptions extends HttpMcpSessionStoreOptions {
 }
 
 export interface HttpMcpRequestContext {
+  authenticated?: boolean;
   identity: string;
   parsedBody?: unknown;
+  peerClassification?: DestinationClassification;
 }
 
 export interface HttpMcpTransportStatus {
@@ -101,7 +113,8 @@ function validateInitializeHeaders(request: Request): Response | undefined {
 
 function wrapStreamingResponse(
   response: Response,
-  finish: () => void
+  finish: () => void,
+  isAuthorizationEpochCurrent: () => boolean
 ): Response {
   if (!response.body) {
     finish();
@@ -117,7 +130,21 @@ function wrapStreamingResponse(
   const body = new ReadableStream<Uint8Array>({
     async pull(controller) {
       try {
+        if (!isAuthorizationEpochCurrent()) {
+          await reader.cancel("EGRESS_POLICY_CHANGED");
+          controller.enqueue(POLICY_CHANGED_SSE);
+          controller.close();
+          finishOnce();
+          return;
+        }
         const result = await reader.read();
+        if (!isAuthorizationEpochCurrent()) {
+          await reader.cancel("EGRESS_POLICY_CHANGED");
+          controller.enqueue(POLICY_CHANGED_SSE);
+          controller.close();
+          finishOnce();
+          return;
+        }
         if (result.done) {
           controller.close();
           finishOnce();
@@ -137,6 +164,13 @@ function wrapStreamingResponse(
   return new Response(body, response);
 }
 
+const policyChangedResponse = (): Response =>
+  jsonRpcError(
+    409,
+    -32_000,
+    "EGRESS_POLICY_CHANGED: Collection policy changed; retry"
+  );
+
 /** Stateful session gateway used by the production `/mcp` route. */
 export class HttpMcpTransport {
   readonly #runtime: HttpMcpTransportRuntime;
@@ -212,6 +246,15 @@ export class HttpMcpTransport {
     let session: HttpMcpSession | undefined;
     let pending: PendingHttpMcpSession | undefined;
     let finished = false;
+    const authorizationEpoch = {
+      value:
+        admission.authorizationEpoch ??
+        this.#runtime.authorizationEpoch ??
+        "egress-epoch-unavailable",
+    };
+    const isAuthorizationEpochCurrent = (): boolean =>
+      this.#runtime.authorizationEpoch === undefined ||
+      authorizationEpoch.value === this.#runtime.authorizationEpoch;
     const finish = (): void => {
       if (finished) return;
       finished = true;
@@ -293,10 +336,53 @@ export class HttpMcpTransport {
         finish();
         return jsonRpcError(403, -32_000, "Forbidden");
       }
-      const response = await transport.handleRequest(
-        request,
-        requestBody === undefined ? undefined : { parsedBody: requestBody }
-      );
+      try {
+        enforceHttpMcpEgress(
+          requestBody,
+          this.#runtime.mcpContext.collections,
+          {
+            authenticated: context.authenticated ?? false,
+            destinationZone:
+              context.peerClassification?.zone ??
+              (context.identity === "loopback" ? "loopback" : "remote"),
+            operationAuthorized: true,
+          }
+        );
+      } catch (error) {
+        if (error instanceof EgressDeniedError) {
+          await pending?.discard();
+          finish();
+          return httpMcpEgressDeniedResponse(error, requestBody);
+        }
+        throw error;
+      }
+      const handle = () =>
+        transport.handleRequest(
+          request,
+          requestBody === undefined ? undefined : { parsedBody: requestBody }
+        );
+      const destinationZone =
+        context.peerClassification?.zone ??
+        (context.identity === "loopback" ? "loopback" : "remote");
+      const response = this.#runtime.mcpContext.runWithEgressContext
+        ? await this.#runtime.mcpContext.runWithEgressContext(
+            {
+              destinationZone,
+              caller: {
+                authenticated: context.authenticated ?? false,
+                operationAuthorized: true,
+              },
+              authorizationEpoch,
+            },
+            handle
+          )
+        : await handle();
+
+      if (!isAuthorizationEpochCurrent()) {
+        await pending?.discard();
+        finish();
+        return policyChangedResponse();
+      }
 
       if (pending) {
         session = pending.session;
@@ -305,7 +391,11 @@ export class HttpMcpTransport {
       }
 
       if (response.headers.get("content-type")?.includes("text/event-stream")) {
-        return wrapStreamingResponse(response, finish);
+        return wrapStreamingResponse(
+          response,
+          finish,
+          isAuthorizationEpochCurrent
+        );
       }
       finish();
       return response;

package/src/mcp/sync-egress.ts

@@ -0,0 +1,24 @@
+/** Fail-closed guard for sync modes that can spawn network-capable commands. */
+
+import type { ToolContext } from "./context";
+
+import { enforceCollectionEgress } from "../core/egress-enforcement";
+
+export const enforceSyncCommandEgress = (
+  ctx: ToolContext,
+  input: {
+    collectionNames?: readonly string[];
+    gitPull?: boolean;
+    runUpdateCmd?: boolean;
+  }
+): void => {
+  if (!(input.gitPull || input.runUpdateCmd)) return;
+  enforceCollectionEgress({
+    collections: ctx.collections,
+    collectionNames: input.collectionNames,
+    action: "export",
+    destinationZone: "remote",
+    caller: { authenticated: true, operationAuthorized: ctx.enableWrite },
+    contentClass: "source",
+  });
+};

package/src/mcp/tools/add-collection.ts

@@ -140,6 +140,10 @@ export function handleAddCollection(
         if (!collection) {
           throw new Error("RUNTIME: Collection missing after add");
         }
+        const invalidation = await ctx.invalidateEgressPolicy?.();
+        if (invalidation) {
+          ctx.advanceRequestAuthorizationEpoch?.(invalidation.policyEpoch);
+        }
 
         const jobId = await ctx.jobManager.startJobWithLock(
           "add",

package/src/mcp/tools/ask.ts

@@ -202,7 +202,7 @@ export const handleAsk = (
         traceSession = started.value ?? undefined;
         modelPorts = await createMcpModelPorts(
           context,
-          args.collection,
+          args.collection ? [args.collection] : undefined,
           dependencies.modelPortFactory,
           { generation: true }
         );

package/src/mcp/tools/context.ts

@@ -119,7 +119,7 @@ export const disposeContextModelOwners = async (
 
 export const createMcpModelPorts = async (
   context: ToolContext,
-  collection?: string,
+  collections?: readonly string[],
   factoryOverride?: McpModelPortFactory,
   options: { generation?: boolean } = {}
 ): Promise<McpModelPorts> => {
@@ -128,6 +128,10 @@ export const createMcpModelPorts = async (
   const lease = factory.acquireModelLease?.();
   const policy = resolveDownloadPolicy(process.env, {});
   const progress = createNonTtyProgressRenderer();
+  const egressCollections = collections?.length
+    ? collections
+    : ("all" as const);
+  const collection = collections?.length === 1 ? collections[0] : undefined;
   const embedUri = resolveModelUri(
     context.config,
     "embed",
@@ -141,6 +145,7 @@ export const createMcpModelPorts = async (
   let vectorIndex: VectorIndexPort | null = null;
   try {
     const embedResult = await factory.createEmbeddingPort(embedUri, {
+      egressCollections,
       policy,
       onProgress: (value) => progress("embed", value),
     });
@@ -160,6 +165,7 @@ export const createMcpModelPorts = async (
     const rerankResult = await factory.createRerankPort(
       resolveModelUri(context.config, "rerank", undefined, collection),
       {
+        egressCollections,
         policy,
         onProgress: (value) => progress("rerank", value),
       }
@@ -169,6 +175,7 @@ export const createMcpModelPorts = async (
       const genResult = await factory.createGenerationPort(
         resolveModelUri(context.config, "gen", undefined, collection),
         {
+          egressCollections,
           policy,
           onProgress: (value) => progress("gen", value),
         }
@@ -269,7 +276,7 @@ export const handleContext = (
       if (!traceStart.ok) throw new Error(traceStart.error.message);
       traceSession = traceStart.value ?? undefined;
       modelPorts = useModels
-        ? await createMcpModelPorts(context, collection)
+        ? await createMcpModelPorts(context, parsed.input.collections)
         : null;
       const capsule = await buildContextCapsule(parsed.input, {
         store: context.store,