@mxf-dev/core 2.0.4 → 3.0.0

package/src/models/agentIdentityReservation.ts

@@ -0,0 +1,77 @@
+/**
+ * Copyright 2024 Brad Anderson
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * @author Brad Anderson <BradA1878@pm.me>
+ * @repository https://github.com/BradA1878/model-exchange-framework
+ * @documentation https://mxf-dev.github.io/mxf/
+ */
+
+import mongoose, { Document, Schema } from 'mongoose';
+
+/**
+ * Permanent tenant ownership of a globally keyed agent identity.
+ *
+ * Reservations are intentionally never removed when an Agent or its channel
+ * keys are deleted. Releasing the row would let another tenant take over the
+ * same agentId and inherit resources that are keyed only by that identifier.
+ */
+export interface IAgentIdentityReservation extends Document<string> {
+    _id: string;
+    agentId: string;
+    ownerId: string;
+    claimedAt: Date;
+    createdAt: Date;
+    updatedAt: Date;
+}
+
+const AgentIdentityReservationSchema = new Schema<IAgentIdentityReservation>(
+    {
+        // MongoDB's built-in _id index is the race barrier. It exists before
+        // any application-created indexes, including during first startup.
+        _id: {
+            type: String,
+            required: true
+        },
+        agentId: {
+            type: String,
+            required: true,
+            immutable: true
+        },
+        ownerId: {
+            type: String,
+            required: true,
+            immutable: true,
+            index: true
+        },
+        claimedAt: {
+            type: Date,
+            required: true,
+            default: Date.now
+        }
+    },
+    {
+        collection: 'agent_identity_reservations',
+        timestamps: true
+    }
+);
+
+// The built-in `_id` index is the correctness boundary; no asynchronously
+// created application index is required before claims are safe.
+const AgentIdentityReservation = mongoose.model<IAgentIdentityReservation>(
+    'AgentIdentityReservation',
+    AgentIdentityReservationSchema
+);
+
+export default AgentIdentityReservation;

package/src/models/channel.ts

@@ -48,6 +48,8 @@ export interface IChannel extends Document {
     maxAgents: number;
     allowAnonymous: boolean;
     showActiveAgents: boolean; // Whether agents can see other agents in the channel
+    allowedTools: string[]; // Empty means no additional channel-level restriction
+    systemLlmEnabled: boolean;
     
     // Channel state
     active: boolean;

package/src/models/channelKey.ts

@@ -51,6 +51,11 @@ export interface IChannelKey extends Document {
     // chose its own agentId, so one shared key let a client present any agent identity.
     agentId: string;
 
+    // Maximum tool capability carried by this credential. A connecting agent
+    // may narrow this list, but can never grant itself tools outside it.
+    // Omission means the curated core-tool maximum; [] denies every tool.
+    allowedTools?: string[];
+
     // Optional name for the key (for user reference)
     name?: string;
     
@@ -93,6 +98,11 @@ const ChannelKeySchema: Schema = new Schema({
         required: true,
         index: true,
     },
+    allowedTools: {
+        type: [String],
+        required: false,
+        default: undefined,
+    },
     name: {
         type: String,
         required: false,

package/src/models/memory.ts

@@ -25,7 +25,7 @@
  * These models define the database structure for different memory types.
  */
 
-import mongoose, { Schema, Document, Model } from 'mongoose';
+import mongoose, { Schema, Model } from 'mongoose';
 import { v4 as uuidv4 } from 'uuid';
 
 import {
@@ -37,8 +37,6 @@ import {
 } from '../types/MemoryTypes.js';
 import {
     MemoryUtilitySubdocument,
-    QValueHistoryEntry,
-    QValueInitSource,
     DEFAULT_UTILITY_SUBDOCUMENT
 } from '../types/MemoryUtilityTypes.js';
 
@@ -51,7 +49,7 @@ const baseMemorySchema = new Schema({
         type: String,
         required: true,
         unique: true,
-        default: () => uuidv4()
+        default: (): string => uuidv4()
     },
     
     // Creation timestamp
@@ -131,14 +129,10 @@ const baseMemorySchema = new Schema({
                 default: 'default'
             }
         }, { _id: false }),
-        default: () => ({
-            qValue: 0.5,
+        default: (): MemoryUtilitySubdocument => ({
+            ...DEFAULT_UTILITY_SUBDOCUMENT,
             qValueHistory: [],
-            retrievalCount: 0,
-            successCount: 0,
-            failureCount: 0,
             lastRewardAt: new Date(),
-            initializedFrom: 'default'
         })
     }
 }, {
@@ -146,7 +140,7 @@ const baseMemorySchema = new Schema({
     strict: false, // Allow for flexible schema evolution
     id: false, // Don't create default MongoDB _id field
     toJSON: {
-        transform: (doc, ret) => {
+        transform: (_document: unknown, ret: Record<string, unknown>): Record<string, unknown> => {
             delete ret._id; // Remove MongoDB _id when converting to JSON
             return ret;
         }
@@ -160,8 +154,7 @@ const agentMemorySchema = new Schema({
     // Reference to Agent ID
     agentId: {
         type: String,
-        required: true,
-        index: true
+        required: true
     },
     
     // Conversation history
@@ -178,8 +171,7 @@ const channelMemorySchema = new Schema({
     // Reference to Channel ID
     channelId: {
         type: String,
-        required: true,
-        index: true
+        required: true
     },
     
     // Shared state visible to all agents in the channel
@@ -223,9 +215,6 @@ const relationshipMemorySchema = new Schema({
     }
 });
 
-// Create compound index for relationship memory
-relationshipMemorySchema.index({ agentId1: 1, agentId2: 1, channelId: 1 }, { unique: true });
-
 // Complete memory models by combining base and specific schemas
 const AgentMemorySchema = new Schema({
     ...baseMemorySchema.obj,
@@ -242,6 +231,14 @@ const RelationshipMemorySchema = new Schema({
     ...relationshipMemorySchema.obj
 });
 
+// Enforce one authoritative document for every memory identity on the final schemas.
+AgentMemorySchema.index({ agentId: 1 }, { unique: true });
+ChannelMemorySchema.index({ channelId: 1 }, { unique: true });
+RelationshipMemorySchema.index(
+    { agentId1: 1, agentId2: 1, channelId: 1 },
+    { unique: true }
+);
+
 // Create indexes for Q-value queries (MULS optimization)
 // Index for sorting by Q-value descending (top performers)
 AgentMemorySchema.index({ 'utility.qValue': -1 });
@@ -296,7 +293,9 @@ export const RelationshipMemory: Model<RelationshipMemoryDocument> =
  * @param scope Memory scope
  * @returns The corresponding memory model
  */
-export const getMemoryModelByScope = (scope: MemoryScope): Model<any> => {
+export const getMemoryModelByScope = (
+    scope: MemoryScope
+): Model<AgentMemoryDocument> | Model<ChannelMemoryDocument> | Model<RelationshipMemoryDocument> => {
     switch (scope) {
         case MemoryScope.AGENT:
             return AgentMemory;

package/src/models/memoryStrata.ts

@@ -30,8 +30,9 @@ import {
   MemoryStratum,
   MemoryImportance,
   MemoryEntry as IMemoryEntry,
+  MemoryContext,
+  MemorySource,
   SurpriseDetection,
-  MemoryPattern
 } from '../types/MemoryStrataTypes.js';
 
 /**
@@ -48,21 +49,8 @@ export interface IMemoryEntryDocument extends Document {
   embedding?: number[];
   importance: MemoryImportance;
   tags: string[];
-  source: {
-    type: string;
-    agentId?: string;
-    channelId?: string;
-    eventId?: string;
-    data?: Record<string, unknown>;
-  };
-  context: {
-    agentId: string;
-    channelId?: string;
-    taskId?: string;
-    orparPhase?: string;
-    timestamp: Date;
-    data?: Record<string, unknown>;
-  };
+  source: MemorySource;
+  context: MemoryContext;
   accessCount: number;
   lastAccessed: Date;
   createdAt: Date;
@@ -200,8 +188,7 @@ const MemoryEntrySchema: Schema = new Schema(
       index: true
     },
     expiresAt: {
-      type: Date,
-      index: true
+      type: Date
     },
     relatedMemories: {
       type: [String],
@@ -237,8 +224,7 @@ const SurpriseHistorySchema: Schema = new Schema(
     },
     timestamp: {
       type: Date,
-      default: Date.now,
-      index: true
+      default: Date.now
     },
     momentarySurprise: {
       type: Number,
@@ -397,7 +383,7 @@ export function memoryEntryToDocument(
     importance: entry.importance,
     tags: entry.tags,
     source: entry.source,
-    context: entry.context as any,
+    context: entry.context,
     accessCount: entry.accessCount,
     lastAccessed: entry.lastAccessed,
     createdAt: entry.createdAt,
@@ -420,8 +406,8 @@ export function documentToMemoryEntry(doc: IMemoryEntryDocument): IMemoryEntry {
     embedding: doc.embedding,
     importance: doc.importance,
     tags: doc.tags,
-    source: doc.source as any,
-    context: doc.context as any,
+    source: doc.source,
+    context: doc.context,
     accessCount: doc.accessCount,
     lastAccessed: doc.lastAccessed,
     createdAt: doc.createdAt,

package/src/models/plan.ts

@@ -41,9 +41,9 @@ export interface IPlan extends Document {
     planId: string;
     title: string;
     createdBy: string;
-    channelId?: string;
+    channelId: string;
     items: IPlanItem[];
-    metadata?: Record<string, any>;
+    metadata?: Record<string, unknown>;
     createdAt: Date;
     updatedAt: Date;
 }
@@ -110,7 +110,7 @@ const PlanSchema: Schema = new Schema(
         },
         channelId: {
             type: String,
-            required: false,
+            required: true,
             index: true
         },
         items: {

package/src/models/taskEffectiveness.ts

@@ -32,6 +32,7 @@ import { TaskEffectivenessMetrics, TaskDefinition } from '../types/Effectiveness
  */
 export interface ITaskEffectiveness extends Document {
     taskId: string;
+    agentId: string;
     channelId: string;
     agentIds: string[];
     definition: TaskDefinition;
@@ -48,7 +49,11 @@ const TaskEffectivenessSchema = new Schema<ITaskEffectiveness>({
     taskId: {
         type: String,
         required: true,
-        unique: true,
+        index: true
+    },
+    agentId: {
+        type: String,
+        required: true,
         index: true
     },
     channelId: {
@@ -62,6 +67,7 @@ const TaskEffectivenessSchema = new Schema<ITaskEffectiveness>({
     }],
     definition: {
         taskId: String,
+        agentId: String,
         channelId: String,
         taskType: { type: String, index: true },
         description: String,
@@ -134,6 +140,7 @@ const TaskEffectivenessSchema = new Schema<ITaskEffectiveness>({
 });
 
 // Indexes for analytics queries
+TaskEffectivenessSchema.index({ agentId: 1, channelId: 1, taskId: 1 }, { unique: true });
 TaskEffectivenessSchema.index({ channelId: 1, 'metrics.metadata.type': 1 });
 TaskEffectivenessSchema.index({ 'metrics.metadata.startTime': 1, 'metrics.metadata.status': 1 });
 TaskEffectivenessSchema.index({ agentIds: 1, completedAt: 1 });
@@ -149,4 +156,4 @@ TaskEffectivenessSchema.pre('save', function(next) {
 });
 
 // Create and export the model
-export const TaskEffectivenessModel = mongoose.model<ITaskEffectiveness>('TaskEffectiveness', TaskEffectivenessSchema);
+export const TaskEffectivenessModel = mongoose.model<ITaskEffectiveness>('TaskEffectiveness', TaskEffectivenessSchema);

package/src/models/user.ts

@@ -73,6 +73,10 @@ export interface IUser extends Document {
     avatar?: string;
     isActive: boolean;
     lastLogin?: Date;
+    /** SHA-256 digest of the only currently valid magic-link nonce. */
+    magicLinkNonceHash?: string;
+    /** Server-side expiry used with the nonce for atomic one-time consumption. */
+    magicLinkExpiresAt?: Date;
     createdAt: Date;
     updatedAt: Date;
     
@@ -131,6 +135,14 @@ const UserSchema = new Schema<IUser>({
     lastLogin: { 
         type: Date
     },
+    magicLinkNonceHash: {
+        type: String,
+        select: false
+    },
+    magicLinkExpiresAt: {
+        type: Date,
+        select: false
+    },
     createdAt: { 
         type: Date, 
         default: Date.now

package/src/protocols/mcp/LlmTestEnvironmentGuard.ts

@@ -0,0 +1,30 @@
+/**
+ * Test-environment containment for external LLM calls.
+ *
+ * Unit and integration test processes must not spend money merely because a
+ * real API key is present in the developer's environment. Tests that
+ * intentionally exercise a live provider have to opt in explicitly.
+ */
+
+export const EXTERNAL_LLM_TEST_OPT_IN_ENV = 'MXF_TEST_ALLOW_EXTERNAL_LLM_CALLS';
+
+/**
+ * Fail before an external provider request can leave a test process.
+ *
+ * Only the exact value `true` enables live calls. This keeps misspellings and
+ * inherited non-empty values from weakening the safety boundary.
+ */
+export function assertExternalLlmCallAllowed(providerName: string): void {
+    if (process.env.NODE_ENV !== 'test') {
+        return;
+    }
+
+    if (process.env[EXTERNAL_LLM_TEST_OPT_IN_ENV] === 'true') {
+        return;
+    }
+
+    throw new Error(
+        `External LLM call blocked for ${providerName} because NODE_ENV=test. ` +
+        `Set ${EXTERNAL_LLM_TEST_OPT_IN_ENV}=true only for an explicitly authorized live-provider test.`
+    );
+}

package/src/protocols/mcp/McpServerTypes.ts

@@ -53,6 +53,15 @@ export interface McpToolHandlerContext {
     agentId?: string;
     /** Channel ID where the request originated */
     channelId?: string;
+    /**
+     * Server-derived credential capability for this exact request. Transport
+     * boundaries populate it from the validated channel key; callers must not
+     * construct it from agent-provided identity or allowlist fields.
+     */
+    authorization?: {
+        keyId: string;
+        allowedTools?: string[];
+    };
     /** Additional context data */
     data?: Record<string, any>;
 }

package/src/protocols/mcp/providers/AnthropicMcpClient.ts

@@ -468,6 +468,8 @@ export class AnthropicMcpClient extends BaseMcpClient {
         context: AgentContext,
         options?: Record<string, any>
     ): Promise<McpApiResponse> {
+        this.assertExternalLlmCallAllowed();
+
         // Structure messages for Anthropic based on context
         const { systemPrompt, messages } = this.structureMessagesFromContext(context);
 

package/src/protocols/mcp/providers/AzureOpenAiMcpClient.ts

@@ -489,6 +489,7 @@ export class AzureOpenAiMcpClient extends BaseMcpClient {
         context: AgentContext,
         options?: Record<string, any>
     ): Promise<McpApiResponse> {
+        this.assertExternalLlmCallAllowed();
         
         // Structure messages for Azure based on context
         const azureMessages = this.structureMessagesFromContext(context);

package/src/protocols/mcp/providers/BaseMcpClient.ts

@@ -29,6 +29,7 @@
 import { Observable, from, of, throwError } from 'rxjs';
 import { map, catchError } from 'rxjs/operators';
 import { createStrictValidator } from '../../../utils/validation.js';
+import { assertExternalLlmCallAllowed } from '../LlmTestEnvironmentGuard.js';
 import { 
     IMcpClient, 
     McpClientConfig, 
@@ -50,6 +51,9 @@ import {
  * Abstract base class for MCP client implementations
  */
 export abstract class BaseMcpClient implements IMcpClient {
+    /** Override only for providers guaranteed to stay on the local machine. */
+    protected isExternalLlmProvider = true;
+
     // Configuration for this client - initialize with empty defaults to satisfy TypeScript
     protected config: McpClientConfig = {
         apiKey: '',
@@ -121,6 +125,13 @@ export abstract class BaseMcpClient implements IMcpClient {
         tools?: McpTool[],
         options?: Record<string, any>
     ): Promise<McpApiResponse>;
+
+    /** Enforce the test-process paid/external LLM safety boundary. */
+    protected assertExternalLlmCallAllowed(): void {
+        if (this.isExternalLlmProvider) {
+            assertExternalLlmCallAllowed(this.constructor.name);
+        }
+    }
     
     /**
      * Send a message to the LLM
@@ -140,6 +151,8 @@ export abstract class BaseMcpClient implements IMcpClient {
         }
         
         try {
+            this.assertExternalLlmCallAllowed();
+
             // Validate messages array
             this.validator.assertIsArray(messages);
             if (messages.length === 0) {

package/src/protocols/mcp/providers/CustomMcpClient.ts

@@ -200,6 +200,13 @@ export class CustomMcpClient extends BaseMcpClient {
         options?: Record<string, any>
     ): Observable<McpApiResponse> {
         return new Observable<McpApiResponse>(subscriber => {
+            try {
+                this.assertExternalLlmCallAllowed();
+            } catch (error) {
+                subscriber.error(error);
+                return;
+            }
+
             this.sendWithContextImpl(context, options)
                 .then(response => {
                     subscriber.next(response);

package/src/protocols/mcp/providers/GeminiMcpClient.ts

@@ -545,6 +545,8 @@ export class GeminiMcpClient extends BaseMcpClient {
         context: AgentContext,
         options?: Record<string, any>
     ): Promise<McpApiResponse> {
+        this.assertExternalLlmCallAllowed();
+
         if (!this.genAiClient) {
             throw new Error('Google Gen AI client not initialized');
         }

package/src/protocols/mcp/providers/OllamaMcpClient.ts

@@ -113,6 +113,8 @@ const logger = new Logger('debug', 'OllamaMcpClient', 'server');
  * Ollama MCP Client implementation
  */
 export class OllamaMcpClient extends BaseMcpClient {
+    protected isExternalLlmProvider = false;
+
     private baseUrl: string;
     private timeout: number;
 
@@ -561,4 +563,4 @@ export class OllamaMcpClient extends BaseMcpClient {
 
         return ollamaMsg;
     }
-}
+}

package/src/protocols/mcp/providers/OpenAiMcpClient.ts

@@ -601,6 +601,8 @@ export class OpenAiMcpClient extends BaseMcpClient {
         context: AgentContext,
         options?: Record<string, any>
     ): Promise<McpApiResponse> {
+        this.assertExternalLlmCallAllowed();
+
         // Structure messages for OpenAI based on context
         const openAiMessages = this.structureMessagesFromContext(context);
 

package/src/protocols/mcp/providers/OpenRouterMcpClient.ts

@@ -664,6 +664,7 @@ export class OpenRouterMcpClient extends BaseMcpClient {
         context: AgentContext,
         options?: Record<string, any>
     ): Promise<McpApiResponse> {
+        this.assertExternalLlmCallAllowed();
 
         // Structure messages for OpenRouter based on context (returns OpenRouter format)
         const openRouterMessages = this.structureMessagesFromContext(context);
@@ -729,6 +730,8 @@ export class OpenRouterMcpClient extends BaseMcpClient {
         options: Record<string, any>,
         onChunk: (chunk: McpStreamChunk) => void
     ): Promise<McpApiResponse> {
+        this.assertExternalLlmCallAllowed();
+
         // Structure and transform messages same as non-streaming path
         const openRouterMessages = this.structureMessagesFromContext(context);
         const converter = getMessageConverter('client');

package/src/protocols/mcp/providers/XaiMcpClient.ts

@@ -426,6 +426,8 @@ export class XaiMcpClient extends BaseMcpClient {
         context: AgentContext,
         options?: Record<string, any>
     ): Promise<McpApiResponse> {
+        this.assertExternalLlmCallAllowed();
+
         // Structure messages for X.ai based on context
         const xaiMessages = this.structureMessagesFromContext(context);
 

package/src/protocols/mcp/security/BrowserTargetGuard.ts

@@ -0,0 +1,64 @@
+/**
+ * Fail-closed network policy for Puppeteer pages used by MXF web tools.
+ *
+ * Checking only the top-level URL is insufficient: redirects, scripts, images,
+ * frames, and fetch/XHR requests can each target a different host. Every browser
+ * request is therefore checked immediately before Puppeteer continues it.
+ */
+
+import type { HTTPRequest, Page } from 'puppeteer';
+
+import { checkHttpTarget } from './HttpTargetGuard.js';
+
+const BROWSER_LOCAL_PROTOCOLS = new Set(['about:', 'blob:', 'data:']);
+
+const isBrowserLocalUrl = (rawUrl: string): boolean => {
+    try {
+        return BROWSER_LOCAL_PROTOCOLS.has(new URL(rawUrl).protocol);
+    } catch {
+        return rawUrl === 'about:blank';
+    }
+};
+
+/** Reject a top-level browser target before allocating a browser or page. */
+export const requireAllowedBrowserTarget = async (rawUrl: string): Promise<void> => {
+    const decision = await checkHttpTarget(rawUrl);
+    if (!decision.allowed) {
+        throw new Error(decision.reason ?? `Browser target '${rawUrl}' is not allowed`);
+    }
+};
+
+export const guardBrowserRequest = async (request: HTTPRequest): Promise<void> => {
+    if (request.isInterceptResolutionHandled()) {
+        return;
+    }
+
+    const rawUrl = request.url();
+    if (isBrowserLocalUrl(rawUrl)) {
+        await request.continue();
+        return;
+    }
+
+    const decision = await checkHttpTarget(rawUrl);
+    if (request.isInterceptResolutionHandled()) {
+        return;
+    }
+    if (!decision.allowed) {
+        await request.abort('blockedbyclient');
+        return;
+    }
+
+    await request.continue();
+};
+
+/** Install the target policy before the first navigation on a Puppeteer page. */
+export const installBrowserTargetGuard = async (page: Page): Promise<void> => {
+    await page.setRequestInterception(true);
+    page.on('request', (request: HTTPRequest) => {
+        void guardBrowserRequest(request).catch(async () => {
+            if (!request.isInterceptResolutionHandled()) {
+                await request.abort('blockedbyclient');
+            }
+        }).catch(() => undefined);
+    });
+};

package/src/protocols/mcp/security/ExternalMcpRegistrationPolicy.ts

@@ -0,0 +1,38 @@
+/**
+ * Policy for caller-supplied stdio MCP server registrations.
+ *
+ * A stdio registration is equivalent to asking the host to execute a command.
+ * It is therefore off by default and may only be exposed by a server entry
+ * point after that entry point has independently established an administrator
+ * principal. Built-in, server-owned configurations do not pass through this
+ * policy because their commands come from source-controlled configuration.
+ */
+
+export const UNSAFE_STDIO_MCP_ENV = 'MXF_UNSAFE_STDIO_MCP_ENABLED';
+
+/**
+ * True only for the exact, explicit opt-in value.
+ */
+export const isUnsafeStdioMcpEnabled = (): boolean => {
+    return process.env[UNSAFE_STDIO_MCP_ENV] === 'true';
+};
+
+/**
+ * External server payloads historically omitted transport and were treated as
+ * stdio, so an absent transport must remain on the dangerous side of the gate.
+ */
+export const isStdioMcpTransport = (transport: unknown): boolean => {
+    return transport === undefined || transport === null || transport === '' || transport === 'stdio';
+};
+
+/**
+ * Fail closed when a caller-controlled registration would execute a process.
+ */
+export const assertUnsafeStdioMcpEnabled = (transport: unknown): void => {
+    if (isStdioMcpTransport(transport) && !isUnsafeStdioMcpEnabled()) {
+        throw new Error(
+            `Caller-supplied stdio MCP registration is disabled. ` +
+            `An administrator must explicitly set ${UNSAFE_STDIO_MCP_ENV}=true to expose this unsafe capability.`
+        );
+    }
+};