@indexnetwork/protocol 0.4.0-rc.12.1 → 0.4.0-rc.13.1

package/dist/shared/interfaces/agent.interface.d.ts

@@ -0,0 +1,176 @@
+/**
+ * Database adapter interface for agent registry operations.
+ * Implemented by the host application and injected via ProtocolDeps.
+ */
+export interface AgentRecord {
+    id: string;
+    ownerId: string;
+    name: string;
+    description: string | null;
+    type: 'personal' | 'system';
+    status: 'active' | 'inactive';
+    metadata: Record<string, unknown>;
+    createdAt: Date;
+    updatedAt: Date;
+}
+export interface AgentTransportRecord {
+    id: string;
+    agentId: string;
+    channel: 'webhook' | 'mcp';
+    config: Record<string, unknown>;
+    priority: number;
+    active: boolean;
+    failureCount: number;
+}
+export interface AgentPermissionRecord {
+    id: string;
+    agentId: string;
+    userId: string;
+    scope: 'global' | 'node' | 'network';
+    scopeId: string | null;
+    actions: string[];
+    createdAt: Date;
+}
+export interface AgentWithRelations extends AgentRecord {
+    transports: AgentTransportRecord[];
+    permissions: AgentPermissionRecord[];
+}
+export interface CreateAgentInput {
+    ownerId: string;
+    name: string;
+    description?: string;
+    type?: 'personal' | 'system';
+    metadata?: Record<string, unknown>;
+}
+export interface CreateTransportInput {
+    agentId: string;
+    channel: 'webhook' | 'mcp';
+    config?: Record<string, unknown>;
+    priority?: number;
+}
+export interface GrantPermissionInput {
+    agentId: string;
+    userId: string;
+    scope?: 'global' | 'node' | 'network';
+    scopeId?: string;
+    actions: string[];
+}
+/**
+ * Database adapter interface for agent registry operations.
+ *
+ * Handles CRUD for agents, their transports, and permission grants.
+ * Implemented by the host application (backend) and injected into the
+ * protocol layer via constructor injection at the composition root.
+ */
+export interface AgentDatabase {
+    /**
+     * Creates a new agent record.
+     * @param input - Agent creation parameters.
+     * @returns The persisted agent record.
+     */
+    createAgent(input: CreateAgentInput): Promise<AgentRecord>;
+    /**
+     * Retrieves an agent by its ID.
+     * @param agentId - The agent UUID.
+     * @returns The agent record, or null if not found.
+     */
+    getAgent(agentId: string): Promise<AgentRecord | null>;
+    /**
+     * Retrieves an agent along with its transports and permissions.
+     * @param agentId - The agent UUID.
+     * @returns The agent with relations, or null if not found.
+     */
+    getAgentWithRelations(agentId: string): Promise<AgentWithRelations | null>;
+    /**
+     * Updates mutable fields on an agent.
+     * @param agentId - The agent UUID.
+     * @param updates - Partial set of fields to update.
+     * @returns The updated agent record, or null if not found.
+     */
+    updateAgent(agentId: string, updates: Partial<Pick<AgentRecord, 'name' | 'description' | 'status' | 'metadata'>>): Promise<AgentRecord | null>;
+    /**
+     * Deletes an agent and its associated transports and permissions.
+     * @param agentId - The agent UUID.
+     */
+    deleteAgent(agentId: string): Promise<void>;
+    /**
+     * Lists all agents owned by a user, including their relations.
+     * @param userId - The owner's user ID.
+     * @returns Array of agents with transports and permissions.
+     */
+    listAgentsForUser(userId: string): Promise<AgentWithRelations[]>;
+    /**
+     * Creates a transport channel for an agent.
+     * @param input - Transport creation parameters.
+     * @returns The persisted transport record.
+     */
+    createTransport(input: CreateTransportInput): Promise<AgentTransportRecord>;
+    /**
+     * Deletes a transport channel.
+     * @param transportId - The transport UUID.
+     */
+    deleteTransport(transportId: string): Promise<void>;
+    /**
+     * Increments the failure counter for a transport channel.
+     * @param transportId - The transport UUID.
+     */
+    recordTransportFailure(transportId: string): Promise<void>;
+    /**
+     * Resets the failure counter for a transport channel after a successful delivery.
+     * @param transportId - The transport UUID.
+     */
+    recordTransportSuccess(transportId: string): Promise<void>;
+    /**
+     * Grants a permission to an agent for a given user and scope.
+     * @param input - Permission grant parameters.
+     * @returns The persisted permission record.
+     */
+    grantPermission(input: GrantPermissionInput): Promise<AgentPermissionRecord>;
+    /**
+     * Revokes a permission by its ID.
+     * @param permissionId - The permission UUID.
+     */
+    revokePermission(permissionId: string): Promise<void>;
+    /**
+     * Checks whether an agent holds a specific permission for a user.
+     * @param agentId - The agent UUID.
+     * @param userId - The user whose permission is being checked.
+     * @param action - The action string to verify (e.g. `"read"`, `"write"`).
+     * @param scope - Optional scope restriction; defaults to global if omitted.
+     * @returns True if the permission exists, false otherwise.
+     */
+    hasPermission(agentId: string, userId: string, action: string, scope?: {
+        type: 'global' | 'node' | 'network';
+        id?: string;
+    }): Promise<boolean>;
+    /**
+     * Returns all agents authorized for a user and action, optionally within a scope.
+     * @param userId - The user to check authorization for.
+     * @param action - The action string (e.g. `"read"`, `"write"`).
+     * @param scope - Optional scope restriction.
+     * @returns Array of authorized agents with their relations.
+     */
+    findAuthorizedAgents(userId: string, action: string, scope?: {
+        type: 'global' | 'node' | 'network';
+        id?: string;
+    }): Promise<AgentWithRelations[]>;
+    /**
+     * Returns the well-known IDs for built-in system agents.
+     * @returns Object mapping system agent roles to their fixed UUIDs.
+     */
+    getSystemAgentIds(): {
+        chatOrchestrator: string;
+        negotiator: string;
+    };
+}
+/**
+ * Fixed UUIDs for built-in system agents.
+ *
+ * These are seeded into the database on first run and must never change,
+ * as they are referenced by foreign keys and hard-coded in protocol logic.
+ */
+export declare const SYSTEM_AGENT_IDS: {
+    readonly chatOrchestrator: "00000000-0000-0000-0000-000000000001";
+    readonly negotiator: "00000000-0000-0000-0000-000000000002";
+};
+//# sourceMappingURL=agent.interface.d.ts.map

package/dist/shared/interfaces/agent.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.interface.d.ts","sourceRoot":"","sources":["../../../src/shared/interfaces/agent.interface.ts"],"names":[],"mappings":"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"}

package/dist/shared/interfaces/agent.interface.js

@@ -0,0 +1,15 @@
+/**
+ * Database adapter interface for agent registry operations.
+ * Implemented by the host application and injected via ProtocolDeps.
+ */
+/**
+ * Fixed UUIDs for built-in system agents.
+ *
+ * These are seeded into the database on first run and must never change,
+ * as they are referenced by foreign keys and hard-coded in protocol logic.
+ */
+export const SYSTEM_AGENT_IDS = {
+    chatOrchestrator: '00000000-0000-0000-0000-000000000001',
+    negotiator: '00000000-0000-0000-0000-000000000002',
+};
+//# sourceMappingURL=agent.interface.js.map

package/dist/shared/interfaces/agent.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.interface.js","sourceRoot":"","sources":["../../../src/shared/interfaces/agent.interface.ts"],"names":[],"mappings":"AAAA;;;GAGG;AA4LH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,gBAAgB,EAAE,sCAAsC;IACxD,UAAU,EAAE,sCAAsC;CAC1C,CAAC"}

package/dist/shared/interfaces/auth.interface.d.ts

@@ -1,15 +1,22 @@
 /**
- * Resolves the authenticated user ID from an incoming request.
+ * Resolves the authenticated MCP identity from an incoming request.
  * Injected into the MCP server factory so the protocol layer
  * stays independent of any specific auth implementation.
  */
 export interface McpAuthResolver {
     /**
-     * Extracts and validates the authenticated user's ID from the request.
+     * Extracts and validates the authenticated identity from the request.
      * @param request - The incoming HTTP request
-     * @returns The authenticated user's UUID
+     * @returns The authenticated user's UUID and optional agent UUID
      * @throws Error if authentication fails (no token, invalid token, etc.)
      */
+    resolveIdentity(request: Request): Promise<{
+        userId: string;
+        agentId?: string;
+    }>;
+    /**
+     * @deprecated Use resolveIdentity instead.
+     */
     resolveUserId(request: Request): Promise<string>;
 }
 //# sourceMappingURL=auth.interface.d.ts.map

package/dist/shared/interfaces/auth.interface.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth.interface.d.ts","sourceRoot":"","sources":["../../../src/shared/interfaces/auth.interface.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;OAKG;IACH,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAClD"}
+{"version":3,"file":"auth.interface.d.ts","sourceRoot":"","sources":["../../../src/shared/interfaces/auth.interface.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;OAKG;IACH,eAAe,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAEjF;;OAEG;IACH,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAClD"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indexnetwork/protocol",
-  "version": "0.4.0-rc.12.1",
+  "version": "0.4.0-rc.13.1",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",