@hailer/mcp 1.1.12 → 1.1.14

package/dist/mcp/utils/role-utils.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Role-Based Access Control Utilities
+ *
+ * Derives user role from workspace member flags and maps roles to ToolGroups.
+ * Used by UserContextCache to determine tool access at context creation time.
+ */
+import { ToolGroup } from '../tool-registry';
+import { UserRole, WorkspaceMember, WorkspaceInfo } from './types';
+/**
+ * Derive user role from workspace member flags
+ * Priority: owner > admin > guest > member
+ *
+ * @param member - Workspace member from v2.core.init
+ * @returns UserRole - 'owner' | 'admin' | 'guest' | 'member'
+ */
+export declare function deriveUserRole(member: WorkspaceMember): UserRole;
+/**
+ * Map user role to allowed ToolGroups
+ *
+ * @param role - User role derived from workspace member
+ * @param enableNuclear - Optional override to disable NUCLEAR even for owners
+ * @returns Array of ToolGroups the user can access
+ */
+export declare function getAllowedGroups(role: UserRole, enableNuclear?: boolean): ToolGroup[];
+/**
+ * Find current user in workspace members array
+ *
+ * @param members - Array of workspace members from init.network.members
+ * @param currentUserId - Current user's ID
+ * @returns WorkspaceMember if found, undefined otherwise
+ */
+export declare function findCurrentUserMember(members: WorkspaceMember[], currentUserId: string): WorkspaceMember | undefined;
+/**
+ * Extract user roles from all workspaces
+ * Returns a map of workspaceId → UserRole
+ *
+ * @param networks - Record of workspace ID to WorkspaceInfo from init.networks
+ * @param currentUserId - Current user's ID
+ * @returns Record mapping workspace IDs to UserRoles
+ */
+export declare function extractWorkspaceRoles(networks: Record<string, WorkspaceInfo>, currentUserId: string): Record<string, UserRole>;
+/**
+ * Get allowed groups for a specific workspace
+ *
+ * @param workspaceRoles - Map of workspace IDs to UserRoles
+ * @param workspaceId - Target workspace ID
+ * @param enableNuclear - Optional override to disable NUCLEAR even for owners
+ * @returns Array of ToolGroups the user can access in the specified workspace
+ */
+export declare function getAllowedGroupsForWorkspace(workspaceRoles: Record<string, UserRole>, workspaceId: string, enableNuclear?: boolean): ToolGroup[];
+/**
+ * Get the highest role across all workspaces
+ * Used to determine which tools to show at startup (max potential access)
+ *
+ * @param workspaceRoles - Map of workspace IDs to UserRoles
+ * @returns Highest UserRole across all workspaces
+ */
+export declare function getMaxRole(workspaceRoles: Record<string, UserRole>): UserRole;
+/**
+ * Check if user has access to a specific ToolGroup in a workspace
+ * Used for runtime permission validation when tools are called with workspaceId
+ *
+ * @param workspaceRoles - Map of workspace IDs to UserRoles
+ * @param currentWorkspaceId - Current default workspace ID
+ * @param targetWorkspaceId - Target workspace ID (or undefined to use current)
+ * @param requiredGroup - ToolGroup required for the operation
+ * @param enableNuclear - Optional override to disable NUCLEAR even for owners
+ * @returns Object with allowed boolean and optional reason string
+ */
+export declare function checkWorkspaceAccess(workspaceRoles: Record<string, UserRole>, currentWorkspaceId: string, targetWorkspaceId: string | undefined, requiredGroup: ToolGroup, enableNuclear?: boolean): {
+    allowed: boolean;
+    reason?: string;
+};
+//# sourceMappingURL=role-utils.d.ts.map

package/dist/mcp/utils/role-utils.js

@@ -0,0 +1,151 @@
+"use strict";
+/**
+ * Role-Based Access Control Utilities
+ *
+ * Derives user role from workspace member flags and maps roles to ToolGroups.
+ * Used by UserContextCache to determine tool access at context creation time.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deriveUserRole = deriveUserRole;
+exports.getAllowedGroups = getAllowedGroups;
+exports.findCurrentUserMember = findCurrentUserMember;
+exports.extractWorkspaceRoles = extractWorkspaceRoles;
+exports.getAllowedGroupsForWorkspace = getAllowedGroupsForWorkspace;
+exports.getMaxRole = getMaxRole;
+exports.checkWorkspaceAccess = checkWorkspaceAccess;
+const tool_registry_1 = require("../tool-registry");
+/**
+ * Derive user role from workspace member flags
+ * Priority: owner > admin > guest > member
+ *
+ * @param member - Workspace member from v2.core.init
+ * @returns UserRole - 'owner' | 'admin' | 'guest' | 'member'
+ */
+function deriveUserRole(member) {
+    if (member.owner)
+        return 'owner';
+    if (member.admin)
+        return 'admin';
+    if (member.guest)
+        return 'guest';
+    return 'member';
+}
+/**
+ * Map user role to allowed ToolGroups
+ *
+ * @param role - User role derived from workspace member
+ * @param enableNuclear - Optional override to disable NUCLEAR even for owners
+ * @returns Array of ToolGroups the user can access
+ */
+function getAllowedGroups(role, enableNuclear = true) {
+    switch (role) {
+        case 'owner':
+            return enableNuclear
+                ? [tool_registry_1.ToolGroup.READ, tool_registry_1.ToolGroup.WRITE, tool_registry_1.ToolGroup.PLAYGROUND, tool_registry_1.ToolGroup.NUCLEAR]
+                : [tool_registry_1.ToolGroup.READ, tool_registry_1.ToolGroup.WRITE, tool_registry_1.ToolGroup.PLAYGROUND];
+        case 'admin':
+            return [tool_registry_1.ToolGroup.READ, tool_registry_1.ToolGroup.WRITE, tool_registry_1.ToolGroup.PLAYGROUND];
+        case 'member':
+            return [tool_registry_1.ToolGroup.READ, tool_registry_1.ToolGroup.WRITE];
+        case 'guest':
+            return [tool_registry_1.ToolGroup.READ];
+    }
+}
+/**
+ * Find current user in workspace members array
+ *
+ * @param members - Array of workspace members from init.network.members
+ * @param currentUserId - Current user's ID
+ * @returns WorkspaceMember if found, undefined otherwise
+ */
+function findCurrentUserMember(members, currentUserId) {
+    return members.find(m => m.uid === currentUserId);
+}
+/**
+ * Extract user roles from all workspaces
+ * Returns a map of workspaceId → UserRole
+ *
+ * @param networks - Record of workspace ID to WorkspaceInfo from init.networks
+ * @param currentUserId - Current user's ID
+ * @returns Record mapping workspace IDs to UserRoles
+ */
+function extractWorkspaceRoles(networks, currentUserId) {
+    const roles = {};
+    for (const [wsId, network] of Object.entries(networks)) {
+        const members = (network.members || []);
+        const member = findCurrentUserMember(members, currentUserId);
+        roles[wsId] = member ? deriveUserRole(member) : 'guest';
+    }
+    return roles;
+}
+/**
+ * Get allowed groups for a specific workspace
+ *
+ * @param workspaceRoles - Map of workspace IDs to UserRoles
+ * @param workspaceId - Target workspace ID
+ * @param enableNuclear - Optional override to disable NUCLEAR even for owners
+ * @returns Array of ToolGroups the user can access in the specified workspace
+ */
+function getAllowedGroupsForWorkspace(workspaceRoles, workspaceId, enableNuclear = true) {
+    const role = workspaceRoles[workspaceId] || 'guest';
+    return getAllowedGroups(role, enableNuclear);
+}
+/**
+ * Get the highest role across all workspaces
+ * Used to determine which tools to show at startup (max potential access)
+ *
+ * @param workspaceRoles - Map of workspace IDs to UserRoles
+ * @returns Highest UserRole across all workspaces
+ */
+function getMaxRole(workspaceRoles) {
+    const roleOrder = ['guest', 'member', 'admin', 'owner'];
+    let maxRole = 'guest';
+    for (const role of Object.values(workspaceRoles)) {
+        if (roleOrder.indexOf(role) > roleOrder.indexOf(maxRole)) {
+            maxRole = role;
+        }
+    }
+    return maxRole;
+}
+/**
+ * Get minimum role required for a ToolGroup
+ * Used for error messages
+ */
+function getRequiredRoleForGroup(group) {
+    switch (group) {
+        case tool_registry_1.ToolGroup.READ:
+            return 'guest';
+        case tool_registry_1.ToolGroup.WRITE:
+            return 'member';
+        case tool_registry_1.ToolGroup.PLAYGROUND:
+            return 'admin';
+        case tool_registry_1.ToolGroup.NUCLEAR:
+            return 'owner';
+        default:
+            return 'owner';
+    }
+}
+/**
+ * Check if user has access to a specific ToolGroup in a workspace
+ * Used for runtime permission validation when tools are called with workspaceId
+ *
+ * @param workspaceRoles - Map of workspace IDs to UserRoles
+ * @param currentWorkspaceId - Current default workspace ID
+ * @param targetWorkspaceId - Target workspace ID (or undefined to use current)
+ * @param requiredGroup - ToolGroup required for the operation
+ * @param enableNuclear - Optional override to disable NUCLEAR even for owners
+ * @returns Object with allowed boolean and optional reason string
+ */
+function checkWorkspaceAccess(workspaceRoles, currentWorkspaceId, targetWorkspaceId, requiredGroup, enableNuclear = true) {
+    const effectiveWsId = targetWorkspaceId || currentWorkspaceId;
+    const role = workspaceRoles[effectiveWsId] || 'guest';
+    const allowedGroups = getAllowedGroups(role, enableNuclear);
+    if (!allowedGroups.includes(requiredGroup)) {
+        return {
+            allowed: false,
+            reason: `Insufficient permissions in workspace '${effectiveWsId.slice(-6)}'. Your role '${role}' doesn't have access to ${requiredGroup} tools. Required: ${getRequiredRoleForGroup(requiredGroup)} or higher.`
+        };
+    }
+    return { allowed: true };
+}
+//# sourceMappingURL=role-utils.js.map

package/dist/mcp/utils/types.d.ts

@@ -2,6 +2,29 @@
  * Shared type definitions for Hailer MCP Server
  * Consolidates interfaces used across multiple files
  */
+/**
+ * User role in workspace (derived from member flags)
+ * Used to determine which ToolGroups are available to the user
+ */
+export type UserRole = 'guest' | 'member' | 'admin' | 'owner';
+/**
+ * Workspace member from v2.core.init response
+ * Contains role flags that determine user permissions
+ *
+ * Schema reference: hailer-api/src/validation/sharedSchemas.ts (validWorkspaceMemberSchema)
+ */
+export interface WorkspaceMember {
+    uid: string;
+    title?: string;
+    owner?: boolean;
+    admin?: boolean;
+    guest?: boolean;
+    inviter?: boolean;
+    feedAdmin?: boolean;
+    customRole?: string;
+    joined: number;
+    fields?: Record<string, string | string[] | null>;
+}
 export type { CleanActivity, FieldValue, WorkflowInfo, PhaseInfo, FieldInfo, UserInfo, } from './data-transformers';
 export interface HailerField {
     data: any[];
@@ -127,6 +150,12 @@ export interface HailerV2CoreInitResponse {
     users: Record<string, HailerUser>;
     [key: string]: any;
 }
+/**
+ * Normalize v2.core.init response: the API returns processes as an object
+ * keyed by process ID, but all tool code expects an array. This converts
+ * the object form to an array with _id set on each entry.
+ */
+export declare function normalizeInitProcesses(init: HailerV2CoreInitResponse): void;
 export interface McpTextContent {
     type: "text";
     text: string;
@@ -173,7 +202,7 @@ export interface WorkspaceInfo {
     _id: string;
     name: string;
     description?: string;
-    members?: string[];
+    members?: WorkspaceMember[];
     settings?: Record<string, any>;
 }
 export interface SignalData {
@@ -248,6 +277,19 @@ export interface DiscussionMessageParams {
     discussionId: string;
     content: string;
 }
+export interface OptimizedDiscussionMessage {
+    _id: string;
+    uid: string;
+    username: string;
+    created: string;
+    type: string;
+    msg: string;
+    replyTo?: string;
+    systemDescription?: string;
+    meta?: any;
+    forwardMessageId?: string;
+    forwardMessage?: OptimizedDiscussionMessage;
+}
 export interface FetchDiscussionParams {
     discussionId: string;
     limit?: number;

package/dist/mcp/utils/types.js

@@ -4,4 +4,18 @@
  * Consolidates interfaces used across multiple files
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeInitProcesses = normalizeInitProcesses;
+/**
+ * Normalize v2.core.init response: the API returns processes as an object
+ * keyed by process ID, but all tool code expects an array. This converts
+ * the object form to an array with _id set on each entry.
+ */
+function normalizeInitProcesses(init) {
+    if (init.processes && !Array.isArray(init.processes)) {
+        init.processes = Object.entries(init.processes).map(([id, p]) => ({
+            _id: id,
+            ...p,
+        }));
+    }
+}
 //# sourceMappingURL=types.js.map

package/dist/mcp/webhook-handler.d.ts

@@ -50,6 +50,8 @@ interface BotEntry {
     enabled: boolean;
     displayName?: string;
     systemPrompt?: string;
+    accessLevel?: string;
+    responseMode?: string;
 }
 interface WorkspaceConfig {
     workspaceId: string;
@@ -61,6 +63,8 @@ interface WorkspaceConfig {
         password: string;
         displayName?: string;
         systemPrompt?: string;
+        accessLevel?: string;
+        responseMode?: string;
     };
     specialists: BotEntry[];
     lastSynced: string;

package/dist/mcp/webhook-handler.js

@@ -222,6 +222,9 @@ function handleBotConfigWebhook(payload) {
     const userId = getFieldValue(payload.fields, 'hailerProfile');
     const schemaConfigStr = getFieldValue(payload.fields, 'schemaConfig');
     const systemPrompt = getFieldValue(payload.fields, 'systemPrompt') || undefined;
+    const accessLevel = getFieldValue(payload.fields, 'accessLevel') || undefined;
+    // responseMode is stored inside schemaConfig JSON, not as a separate field
+    let responseMode;
     // Validate required fields
     if (!email || !password) {
         logger.warn('Webhook missing credentials', {
@@ -245,6 +248,7 @@ function handleBotConfigWebhook(payload) {
             const schemaConfig = JSON.parse(schemaConfigStr);
             deployedPhaseId = schemaConfig.deployedPhaseId;
             retiredPhaseId = schemaConfig.retiredPhaseId;
+            responseMode = schemaConfig.responseMode || undefined;
         }
         catch (e) {
             logger.warn('Failed to parse schemaConfig', { schemaConfigStr });
@@ -264,6 +268,8 @@ function handleBotConfigWebhook(payload) {
         enabled,
         displayName: payload.name, // Activity name from Agent Directory
         systemPrompt,
+        accessLevel,
+        responseMode,
     };
     let action;
     // Handle orchestrator
@@ -276,6 +282,8 @@ function handleBotConfigWebhook(payload) {
                 password,
                 displayName: payload.name,
                 systemPrompt,
+                accessLevel,
+                responseMode,
             };
             action = 'update';
             logger.info('Updated orchestrator', { workspaceId, email: (0, config_1.maskEmail)(email), displayName: payload.name });

package/dist/mcp-server.d.ts

@@ -10,6 +10,7 @@ import { ToolRegistry } from './mcp/tool-registry';
 declare module 'express-serve-static-core' {
     interface Request {
         logger: Logger;
+        apiKey?: string;
     }
 }
 export interface MCPServerConfig {
@@ -22,18 +23,38 @@ export interface MCPServerConfig {
     }>>;
 }
 export declare class MCPServerService {
+    private static readonly ENDPOINTS;
     private app;
     private server?;
     private logger;
     private config;
     private toolRegistry;
+    private appConfig;
     constructor(config: MCPServerConfig);
     private setupMiddleware;
+    private escapeHtml;
+    private getBaseUrl;
     private setupRoutes;
+    private extractBearerToken;
+    private setupSseStream;
+    private generateSessionId;
     /**
-     * Check if agent has access to a specific tool
+     * Strict access control for /api/mcp — returns false on catch (no config = no access)
      */
-    private canAccessTool;
+    private canAccessToolStrict;
+    /**
+     * Permissive access control for Cowork — allows non-NUCLEAR tools on catch (OAuth sessions)
+     */
+    private canAccessToolPermissive;
+    /**
+     * Cowork MCP JSON-RPC handler for /api/cowork/mcp (OAuth multi-user).
+     * Permissive access control, contextType filter, OAuth 401 flow.
+     */
+    private handleCoworkMcp;
+    /**
+     * Send MCP success response via SSE
+     */
+    private sendMcpResult;
     /**
      * Send MCP error response
      */