@indexnetwork/protocol 22.0.0-rc.499.1 → 64.0.0

package/dist/mcp/elicitation.dispatcher.d.ts

@@ -1,36 +0,0 @@
-import type { Question } from "../questions/question.schema.js";
-import type { ChatMessageWriter } from "../shared/interfaces/chat-message-writer.interface.js";
-import { buildElicitationCreate } from "./elicitation.builder.js";
-export type ElicitResultLike = {
-    action: "accept";
-    content?: {
-        choice?: unknown;
-    };
-} | {
-    action: "decline";
-} | {
-    action: "cancel";
-};
-export type ElicitInputFn = (params: ReturnType<typeof buildElicitationCreate>) => Promise<ElicitResultLike>;
-export interface DispatchElicitationsParams {
-    userId: string;
-    questions: Question[];
-    elicitInput: ElicitInputFn;
-    /**
-     * Optional. When absent, elicitations still dispatch (so users aren't
-     * left mid-flow on a misconfiguration), but accepted answers are dropped
-     * with a one-shot warn. See dispatcher body.
-     */
-    chatMessageWriter?: ChatMessageWriter;
-}
-/**
- * Sequentially dispatches one `elicitation/create` per question. On accept,
- * flattens the choice and posts it via the ChatMessageWriter. `cancel` breaks
- * the loop; `decline` is a no-op. A transport throw breaks the loop with a
- * warning. An addUserMessage throw logs and continues (doesn't halt the loop).
- * Empty `questions` is a no-op.
- *
- * Caller is responsible for the capability check — this function only knows
- * how to dispatch.
- */
-export declare function dispatchElicitations({ userId, questions, elicitInput, chatMessageWriter, }: DispatchElicitationsParams): Promise<void>;

package/dist/mcp/elicitation.dispatcher.js

@@ -1,86 +0,0 @@
-import { protocolLogger } from "../shared/observability/protocol.logger.js";
-import { buildElicitationCreate, flattenChoice } from "./elicitation.builder.js";
-const logger = protocolLogger("McpElicitation");
-/** Narrowing guard for elicitation replies received from MCP clients. */
-function isElicitResult(value) {
-    if (typeof value !== "object" || value === null)
-        return false;
-    const action = value.action;
-    return action === "accept" || action === "decline" || action === "cancel";
-}
-/**
- * Sequentially dispatches one `elicitation/create` per question. On accept,
- * flattens the choice and posts it via the ChatMessageWriter. `cancel` breaks
- * the loop; `decline` is a no-op. A transport throw breaks the loop with a
- * warning. An addUserMessage throw logs and continues (doesn't halt the loop).
- * Empty `questions` is a no-op.
- *
- * Caller is responsible for the capability check — this function only knows
- * how to dispatch.
- */
-export async function dispatchElicitations({ userId, questions, elicitInput, chatMessageWriter, }) {
-    if (questions.length === 0)
-        return;
-    if (!chatMessageWriter) {
-        // Misconfiguration: composition root forgot to wire the writer. We still
-        // proceed with elicitations so the user isn't silently left hanging, but
-        // surface the gap once at loop start so it's visible in protocol logs.
-        logger.warn("chat_message_writer_absent_responses_will_drop", {
-            userId,
-            questionCount: questions.length,
-        });
-    }
-    for (const question of questions) {
-        const elicitation = buildElicitationCreate(question);
-        let rawReply;
-        try {
-            rawReply = await elicitInput(elicitation);
-        }
-        catch (err) {
-            logger.warn("elicitation_failed", {
-                title: question.title,
-                error: err instanceof Error ? err.message : String(err),
-            });
-            break;
-        }
-        // The reply is runtime data from the MCP client — validate the shape
-        // before branching. A malformed reply (null, missing action, unknown
-        // action) is treated as a no-op so we don't persist anything unsafe.
-        if (!isElicitResult(rawReply)) {
-            logger.warn("elicitation_response_malformed", { title: question.title });
-            continue;
-        }
-        const reply = rawReply;
-        if (reply.action === "cancel")
-            break;
-        // Require an explicit `accept` — `decline` and any future / unknown
-        // action both fall through to no-op rather than being treated as
-        // accepted responses.
-        if (reply.action !== "accept")
-            continue;
-        const flat = flattenChoice(question, reply.content?.choice);
-        if (flat === null)
-            continue;
-        if (!chatMessageWriter)
-            continue;
-        try {
-            const writeResult = await chatMessageWriter.addUserMessage(userId, flat);
-            if (writeResult === null) {
-                // User has no chat session — the accepted answer is dropped here.
-                // Day-one behavior: log and continue. Future iterations may surface
-                // the answer back through the tool result envelope for clients to
-                // resurface, but that's out of scope for this slice.
-                logger.warn("chat_message_write_skipped_no_session", {
-                    userId,
-                    title: question.title,
-                });
-            }
-        }
-        catch (err) {
-            logger.warn("chat_message_write_failed", {
-                title: question.title,
-                error: err instanceof Error ? err.message : String(err),
-            });
-        }
-    }
-}

package/dist/mcp/mcp.authorization-policy.d.ts

@@ -1,252 +0,0 @@
-import { z } from 'zod';
-import type { McpResolvedIdentity } from '../shared/schemas/mcp-auth.schema.js';
-import type { McpActivityCaller } from '../shared/agent/activity-projection.js';
-/** Canonical MCP permission actions. */
-export declare const MCP_PERMISSION_ACTIONS: readonly ["manage:identity", "manage:premises", "manage:intents", "manage:networks", "manage:opportunities", "manage:negotiations"];
-export declare const McpPermissionActionSchema: z.ZodEnum<["manage:identity", "manage:premises", "manage:intents", "manage:networks", "manage:opportunities", "manage:negotiations"]>;
-export type McpPermissionAction = z.infer<typeof McpPermissionActionSchema>;
-export declare const McpToolPermissionRequirementSchema: z.ZodObject<{
-    action: z.ZodEnum<["manage:identity", "manage:premises", "manage:intents", "manage:networks", "manage:opportunities", "manage:negotiations"]>;
-    /**
-     * Capability reach only. Entity ownership, membership, approval, and exact
-     * scope checks remain in the capability handler.
-     */
-    reach: z.ZodDefault<z.ZodEnum<["principal", "network"]>>;
-}, "strict", z.ZodTypeAny, {
-    action: "manage:negotiations" | "manage:intents" | "manage:opportunities" | "manage:identity" | "manage:premises" | "manage:networks";
-    reach: "network" | "principal";
-}, {
-    action: "manage:negotiations" | "manage:intents" | "manage:opportunities" | "manage:identity" | "manage:premises" | "manage:networks";
-    reach?: "network" | "principal" | undefined;
-}>;
-export type McpToolPermissionRequirement = z.infer<typeof McpToolPermissionRequirementSchema>;
-export type McpToolPermissionMap = ReadonlyMap<string, McpToolPermissionRequirement>;
-/**
- * Runtime-validates a capability-owned tool-to-permission mapping.
- */
-export declare function defineMcpToolPermissionMap(mapping: Readonly<Record<string, McpToolPermissionRequirement>>): McpToolPermissionMap;
-/**
- * Exact full-standalone Hermes MCP surface. Every admitted tool maps to one
- * canonical action; absence is denial, including human-only, deletion,
- * permission-management, agent-administration, and retired aliases.
- */
-export declare const HERMES_AGENT_MCP_TOOL_PERMISSIONS: McpToolPermissionMap;
-export declare const McpToolAccessRuleSchema: z.ZodEffects<z.ZodObject<{
-    access: z.ZodEnum<["permission", "authenticated", "human_only", "agent_admin", "informational", "delivery_only", "removed"]>;
-    actions: z.ZodOptional<z.ZodArray<z.ZodEnum<["manage:identity", "manage:premises", "manage:intents", "manage:networks", "manage:opportunities", "manage:negotiations"]>, "many">>;
-    reach: z.ZodEnum<["principal", "network"]>;
-}, "strict", z.ZodTypeAny, {
-    reach: "network" | "principal";
-    access: "removed" | "permission" | "authenticated" | "human_only" | "agent_admin" | "informational" | "delivery_only";
-    actions?: ("manage:negotiations" | "manage:intents" | "manage:opportunities" | "manage:identity" | "manage:premises" | "manage:networks")[] | undefined;
-}, {
-    reach: "network" | "principal";
-    access: "removed" | "permission" | "authenticated" | "human_only" | "agent_admin" | "informational" | "delivery_only";
-    actions?: ("manage:negotiations" | "manage:intents" | "manage:opportunities" | "manage:identity" | "manage:premises" | "manage:networks")[] | undefined;
-}>, {
-    reach: "network" | "principal";
-    access: "removed" | "permission" | "authenticated" | "human_only" | "agent_admin" | "informational" | "delivery_only";
-    actions?: ("manage:negotiations" | "manage:intents" | "manage:opportunities" | "manage:identity" | "manage:premises" | "manage:networks")[] | undefined;
-}, {
-    reach: "network" | "principal";
-    access: "removed" | "permission" | "authenticated" | "human_only" | "agent_admin" | "informational" | "delivery_only";
-    actions?: ("manage:negotiations" | "manage:intents" | "manage:opportunities" | "manage:identity" | "manage:premises" | "manage:networks")[] | undefined;
-}>;
-export type McpToolAccessRule = z.infer<typeof McpToolAccessRuleSchema>;
-export type McpToolAccessRuleMap = ReadonlyMap<string, McpToolAccessRule>;
-/** Runtime-validates a complete static MCP tool access matrix. */
-export declare function defineMcpToolAccessRules(rules: Readonly<Record<string, McpToolAccessRule>>): McpToolAccessRuleMap;
-/**
- * Canonical MCP tool authorization matrix.
- *
- * Every tool registered by `createToolRegistry` is classified. Tool handlers
- * retain domain ownership, membership, exact-scope, and approval checks.
- */
-export declare const CANONICAL_MCP_TOOL_ACCESS_RULES: McpToolAccessRuleMap;
-/** Tools visible on the REST Tool API while web/CLI onboarding is incomplete. MCP does not use this allowlist. */
-export declare const ONBOARDING_ALLOWED: ReadonlySet<string>;
-/** Agent administration inventory. */
-export declare const MCP_AGENT_ADMIN_TOOLS: ReadonlySet<string>;
-/** Informational inventory retained as a convenience export. */
-export declare const MCP_INFORMATIONAL_TOOLS: ReadonlySet<string>;
-export declare const McpPolicyAgentSnapshotSchema: z.ZodObject<{
-    id: z.ZodString;
-    ownerId: z.ZodString;
-    type: z.ZodEnum<["personal", "external", "system"]>;
-    status: z.ZodEnum<["active", "inactive"]>;
-    permissions: z.ZodArray<z.ZodObject<{
-        agentId: z.ZodString;
-        userId: z.ZodString;
-        scope: z.ZodEnum<["global", "node", "network"]>;
-        scopeId: z.ZodNullable<z.ZodString>;
-        actions: z.ZodArray<z.ZodString, "many">;
-    }, "strict", z.ZodTypeAny, {
-        userId: string;
-        scope: "network" | "global" | "node";
-        scopeId: string | null;
-        actions: string[];
-        agentId: string;
-    }, {
-        userId: string;
-        scope: "network" | "global" | "node";
-        scopeId: string | null;
-        actions: string[];
-        agentId: string;
-    }>, "many">;
-}, "strict", z.ZodTypeAny, {
-    id: string;
-    type: "system" | "personal" | "external";
-    status: "active" | "inactive";
-    permissions: {
-        userId: string;
-        scope: "network" | "global" | "node";
-        scopeId: string | null;
-        actions: string[];
-        agentId: string;
-    }[];
-    ownerId: string;
-}, {
-    id: string;
-    type: "system" | "personal" | "external";
-    status: "active" | "inactive";
-    permissions: {
-        userId: string;
-        scope: "network" | "global" | "node";
-        scopeId: string | null;
-        actions: string[];
-        agentId: string;
-    }[];
-    ownerId: string;
-}>;
-export type McpPolicyAgentSnapshot = z.infer<typeof McpPolicyAgentSnapshotSchema>;
-export declare const McpPrincipalProfileSchema: z.ZodEnum<["session_human", "enrollment_key", "unregistered_key", "registered_global_agent", "registered_network_agent", "hermes_agent", "delivery_agent", "invalid_agent"]>;
-export type McpPrincipalProfile = z.infer<typeof McpPrincipalProfileSchema>;
-export declare const McpCapabilitySubjectSchema: z.ZodObject<{
-    profile: z.ZodEnum<["session_human", "enrollment_key", "unregistered_key", "registered_global_agent", "registered_network_agent", "hermes_agent", "delivery_agent", "invalid_agent"]>;
-    userId: z.ZodString;
-    agentId: z.ZodOptional<z.ZodString>;
-    agentType: z.ZodOptional<z.ZodEnum<["personal", "external", "system"]>>;
-    networkScopeId: z.ZodNullable<z.ZodString>;
-    permissions: z.ZodArray<z.ZodEnum<["manage:identity", "manage:premises", "manage:intents", "manage:networks", "manage:opportunities", "manage:negotiations"]>, "many">;
-}, "strict", z.ZodTypeAny, {
-    userId: string;
-    profile: "session_human" | "enrollment_key" | "unregistered_key" | "registered_global_agent" | "registered_network_agent" | "hermes_agent" | "delivery_agent" | "invalid_agent";
-    networkScopeId: string | null;
-    permissions: ("manage:negotiations" | "manage:intents" | "manage:opportunities" | "manage:identity" | "manage:premises" | "manage:networks")[];
-    agentId?: string | undefined;
-    agentType?: "system" | "personal" | "external" | undefined;
-}, {
-    userId: string;
-    profile: "session_human" | "enrollment_key" | "unregistered_key" | "registered_global_agent" | "registered_network_agent" | "hermes_agent" | "delivery_agent" | "invalid_agent";
-    networkScopeId: string | null;
-    permissions: ("manage:negotiations" | "manage:intents" | "manage:opportunities" | "manage:identity" | "manage:premises" | "manage:networks")[];
-    agentId?: string | undefined;
-    agentType?: "system" | "personal" | "external" | undefined;
-}>;
-export type McpCapabilitySubject = z.infer<typeof McpCapabilitySubjectSchema>;
-export type ResolveMcpCapabilitySubjectInput = {
-    identity: McpResolvedIdentity;
-    agent?: McpPolicyAgentSnapshot | null;
-};
-/**
- * Central capability-loading interpretation of a stored permission row's raw
- * actions. Canonical actions pass through; retired actions project per
- * {@link LEGACY_STORED_ACTION_PROJECTION}; every unknown action fails closed
- * (ignored). Owner/scope matching is applied by the caller BEFORE this runs, so
- * this function never widens the scope a grant applies to.
- */
-export declare function projectStoredPermissionActions(actions: readonly string[]): McpPermissionAction[];
-/**
- * Resolves a request-local, runtime-validated principal profile.
- */
-export declare function resolveMcpCapabilitySubject(input: ResolveMcpCapabilitySubjectInput): McpCapabilitySubject;
-/**
- * Maps a resolved capability subject to the typed caller context consumed by
- * the centralized activity-summary projection. Session humans own the
- * summarized data and receive the full owner view; every other profile is
- * projected as an agent bounded by its granted permissions and (for network
- * agents) its bound community.
- */
-export declare function resolveMcpActivityCaller(subject: McpCapabilitySubject): McpActivityCaller;
-export declare const McpCapabilityDecisionReasonSchema: z.ZodEnum<["session_human", "enrollment", "authenticated", "agent_self_read", "informational", "permission_granted", "delivery", "enrollment_required", "unregistered_principal", "invalid_agent", "agent_admin_denied", "human_read_own_agent_denied", "human_only", "permission_missing", "delivery_required", "removed", "tool_unclassified"]>;
-export type McpCapabilityDecision = {
-    allowed: boolean;
-    reason: z.infer<typeof McpCapabilityDecisionReasonSchema>;
-    reach?: 'principal' | 'network';
-    requiredPermissions?: McpPermissionAction[];
-};
-export type McpCapabilityDecisionReason = z.infer<typeof McpCapabilityDecisionReasonSchema>;
-/**
- * Safe, host-facing description of a single authorization denial. It carries
- * ONLY the caller profile, the tool, and the policy reason/reach — never a
- * token, API key, bearer credential, raw header, or tool-argument payload.
- * `userId`/`agentId`/`networkScopeId` are opaque principal identifiers, not
- * secrets. Constructed centrally in {@link buildMcpAuthorizationDenialEvent}
- * so no call site can widen it with sensitive fields.
- */
-export type McpAuthorizationDenialEvent = {
-    /** Which JSON-RPC boundary produced the denial. */
-    phase: 'tools/call' | 'tools/list';
-    /** The classified tool the caller attempted. */
-    toolName: string;
-    /** The resolved principal profile (never the credential that produced it). */
-    profile: McpPrincipalProfile;
-    /** The policy decision reason. */
-    reason: McpCapabilityDecisionReason;
-    /** Capability reach of the tool rule, when the rule was found. */
-    reach?: 'principal' | 'network';
-    /** The any-of permissions the tool required, when applicable. */
-    requiredPermissions?: McpPermissionAction[];
-    /** Opaque owning-user identifier. */
-    userId: string;
-    /** Opaque agent identifier, present only for agent principals. */
-    agentId?: string;
-    /** Bound network scope for network agents; null otherwise. */
-    networkScopeId: string | null;
-};
-/**
- * Host-injected authorization observability seam. The protocol emits
- * structured, secret-free denial events at the host boundary; the host decides
- * how to record them. Implementations MUST NOT throw affect the decision — the
- * server calls this defensively and ignores observer failures (fail-closed is
- * preserved regardless).
- */
-export interface McpAuthorizationObserver {
-    onCapabilityDenied(event: McpAuthorizationDenialEvent): void;
-}
-/**
- * Builds a safe denial event from a resolved subject and a denial decision.
- * Only whitelisted, non-sensitive fields are copied across; the caller's
- * granted permissions, credentials, headers, and tool arguments are never
- * included.
- */
-export declare function buildMcpAuthorizationDenialEvent(input: {
-    phase: 'tools/call' | 'tools/list';
-    toolName: string;
-    subject: McpCapabilitySubject;
-    decision: McpCapabilityDecision;
-}): McpAuthorizationDenialEvent;
-export type McpCapabilityPolicyOptions = {
-    /** Complete static rule map; defaults to the canonical production matrix. */
-    toolRules?: McpToolAccessRuleMap;
-};
-/**
- * Reusable MCP capability policy. It stores static rules only; caller-specific
- * subjects and decisions are never retained.
- */
-export declare class McpCapabilityPolicy {
-    private readonly toolRules;
-    constructor(options?: McpCapabilityPolicyOptions);
-    /**
-     * Decides whether a resolved caller may use one classified tool.
-     */
-    authorize(subject: McpCapabilitySubject, toolName: string): McpCapabilityDecision;
-    /**
-     * Filters a static inventory and returns a fresh, uncached caller list.
-     */
-    visibleToolNames(subject: McpCapabilitySubject, toolNames: readonly string[]): string[];
-    /** Returns the static classification for inventory tests and host composition. */
-    ruleFor(toolName: string): McpToolAccessRule | undefined;
-}
-/** Canonical production options explicitly passed by the host composition. */
-export declare const CANONICAL_MCP_CAPABILITY_POLICY_OPTIONS: McpCapabilityPolicyOptions;