@enfyra/mcp-server 0.0.72 → 0.0.74

package/README.md

@@ -221,10 +221,12 @@ When an LLM builds a Nuxt, Next, or other SSR frontend for Enfyra, follow the sa
 
 ## Tools (summary)
 
-Metadata, examples, query/CRUD, method management, route/handler/hook, tables/columns, reload cache, logs, user/roles, login, menu/extension, `get_enfyra_api_context`. For full tool list and behavior, see the app after enabling MCP or the source in `src/mcp-server-entry.mjs`.
+Metadata, examples, query/CRUD, method management, route access audit/grant, route/handler/hook, tables/columns, reload cache, logs, user/roles, login, menu/extension, `get_enfyra_api_context`. For full tool list and behavior, see the app after enabling MCP or the source in `src/mcp-server-entry.mjs`.
 
 Use `get_enfyra_examples` when asking an LLM to generate concrete Enfyra implementation patterns. It returns categorized examples for SSR app auth/OAuth/proxy setup, schema/relations, queries/deep, handlers/hooks, permissions/RLS, websocket, flows, files, and extensions.
 
+For authenticated route access, use `audit_route_access` before changing permissions and `ensure_route_access` to grant access by `path` plus `roleName`/`roleId` or `allowedUserIds`. `ensure_route_access` resolves route, role, and method ids, validates that requested methods are available on the route, merges existing methods by default, and reloads routes.
+
 ## Security
 
 API calls use JWT (MCP auto-refreshes). Permissions are enforced by Enfyra.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enfyra/mcp-server",
-  "version": "0.0.72",
+  "version": "0.0.74",
   "description": "MCP server for Enfyra - manage your Enfyra instance via Claude Code",
   "type": "module",
   "license": "MIT",

package/src/lib/mcp-examples.js

@@ -679,6 +679,26 @@ return @DATA\`
     title: 'Route permissions, guards, field permissions, column rules, and RLS',
     useWhen: 'Use when securing routes or shaping what fields a user can read/write.',
     examples: [
+      {
+        name: 'Audit and grant authenticated route access',
+        code: `audit_route_access({
+  path: "/orders",
+  roleName: "user",
+  methods: ["GET", "POST"]
+})
+
+ensure_route_access({
+  path: "/orders",
+  roleName: "user",
+  methods: ["GET", "POST"],
+  description: "Authenticated users can list and create their own orders."
+})`,
+        notes: [
+          'Use route permissions for authenticated access. The tool resolves role and method ids, validates the route available methods, merges existing methods, and reloads routes.',
+          'Handlers or pre-hooks must still enforce owner or tenant scope; route permission only lets the request pass RoleGuard.',
+          'Use publishedMethods only for anonymous public access.',
+        ],
+      },
       {
         name: 'Publish read-only route',
         code: `update_record({

package/src/lib/mcp-instructions.js

@@ -72,7 +72,8 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '',
     '### Routes vs tables (custom endpoints, handlers, hooks)',
     '- REST-first workflow for any feature: **`inspect_feature`** to locate candidates → **`inspect_table`** for table/field/relation/rule context → **`inspect_route`** for handlers/hooks/guards/permissions → **`test_rest_endpoint`** to verify the actual HTTP behavior.',
-    '- Use **`create_column_rule`** for standard request validation, **`create_field_permission`** for per-field read/create/update rules, **`create_route_permission`** for authenticated route access, and **`create_guard`** for pre/post-auth request gates.',
+    '- Use **`audit_route_access`** before debugging route 403s or granting access. Use **`ensure_route_access`** for authenticated role/user route access because it resolves route, role, method ids, validates route.availableMethods, merges existing permissions, and reloads routes. Use low-level **`create_route_permission`** only when you intentionally need a new raw permission row.',
+    '- Use **`create_column_rule`** for standard request validation, **`create_field_permission`** for per-field read/create/update rules, and **`create_guard`** for pre/post-auth request gates.',
     '- Prefer these REST inspection/operator tools over raw `query_table` on system tables when changing route behavior. They resolve ids, methods, route paths, code previews, and cache reloads for the model.',
     '- If the user asks for a **new route**, **URL path**, **custom API endpoint**, **handler**, **pre-hook**, **post-hook**, or to **test** that kind of logic: use MCP **`create_route`** and **omit `mainTableId`**. `mainTable` is only a marker for canonical table routes like `/orders`; custom paths such as `/orders/stats`, `/reports/summary`, `/auth/login`, or `/me` must not set it.',
     '- **Wrong pattern:** calling **`create_table`** just to get an HTTP path, then overriding handlers on the **default** auto route `/{table_name}`. That adds unnecessary schema and breaks the usual CRUD surface for that table.',

package/src/lib/route-permission-tools.js

@@ -0,0 +1,160 @@
+export function normalizeMethodName(method) {
+  return String(method || '').trim().toUpperCase();
+}
+
+export function normalizeMethodNames(methods) {
+  return [...new Set((methods || []).map(normalizeMethodName).filter(Boolean))];
+}
+
+export function getRecordId(record) {
+  return record?.id ?? record?._id ?? null;
+}
+
+export function getReferenceId(value) {
+  return typeof value === 'object' && value !== null ? getRecordId(value) : value;
+}
+
+export function sameRecordId(a, b) {
+  if (a === null || a === undefined || b === null || b === undefined) return false;
+  return String(a) === String(b);
+}
+
+export function resolveRoleByNameOrId(roles, { roleId, roleName } = {}) {
+  if (roleId && roleName) {
+    throw new Error('Provide roleId or roleName, not both.');
+  }
+  if (!roleId && !roleName) return null;
+  const normalizedRoleName = roleName ? String(roleName).trim().toLowerCase() : null;
+  const role = roles.find((item) => (
+    roleId
+      ? sameRecordId(getRecordId(item), roleId)
+      : String(item?.name || '').trim().toLowerCase() === normalizedRoleName
+  ));
+  if (!role) throw new Error(`Role not found: ${roleId || roleName}`);
+  return role;
+}
+
+export function methodNamesFromRecords(methods, methodIdNameMap = {}) {
+  return normalizeMethodNames((methods || []).map((method) => (
+    method?.name || method?.method || methodIdNameMap[String(getRecordId(method))] || method
+  )));
+}
+
+export function routeAvailableMethodNames(route, methodIdNameMap = {}) {
+  return methodNamesFromRecords(route?.availableMethods || [], methodIdNameMap);
+}
+
+export function routePublishedMethodNames(route, methodIdNameMap = {}) {
+  return methodNamesFromRecords(route?.publishedMethods || [], methodIdNameMap);
+}
+
+export function permissionMethodNames(permission, methodIdNameMap = {}) {
+  return methodNamesFromRecords(permission?.methods || [], methodIdNameMap);
+}
+
+export function validateMethodsForRoute(route, methods, methodMap, methodIdNameMap = {}) {
+  const normalizedMethods = normalizeMethodNames(methods);
+  const knownMethods = new Set(Object.keys(methodMap || {}).map(normalizeMethodName));
+  const unknown = normalizedMethods.filter((method) => !knownMethods.has(method));
+  if (unknown.length) {
+    throw new Error(`Unknown method_definition.name values: ${unknown.join(', ')}`);
+  }
+
+  const availableMethods = routeAvailableMethodNames(route, methodIdNameMap);
+  if (availableMethods.length) {
+    const unavailable = normalizedMethods.filter((method) => !availableMethods.includes(method));
+    if (unavailable.length) {
+      throw new Error(`Route ${route?.path} does not list methods as available: ${unavailable.join(', ')}. Available: ${availableMethods.join(', ')}`);
+    }
+  }
+
+  return normalizedMethods;
+}
+
+export function sortedIdStrings(values) {
+  return [...new Set((values || []).map((value) => String(getReferenceId(value))).filter(Boolean))].sort();
+}
+
+export function sameIdSet(a, b) {
+  const left = sortedIdStrings(a);
+  const right = sortedIdStrings(b);
+  return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+
+export function routePermissionMatchesScope(permission, { roleId, allowedUserIds } = {}) {
+  const expectedUsers = sortedIdStrings(allowedUserIds);
+  const permissionUsers = sortedIdStrings(permission?.allowedUsers || []);
+  const permissionRoleId = getReferenceId(permission?.role);
+
+  if (roleId && !sameRecordId(permissionRoleId, roleId)) return false;
+  if (!roleId && permissionRoleId !== null && permissionRoleId !== undefined) return false;
+  return sameIdSet(permissionUsers, expectedUsers);
+}
+
+export function findRoutePermission(routePermissions, routeId, scope) {
+  return (routePermissions || []).find((permission) => (
+    sameRecordId(getReferenceId(permission?.route), routeId)
+    && routePermissionMatchesScope(permission, scope)
+  )) || null;
+}
+
+export function mergeMethodNames(existingMethods, requestedMethods, mode = 'merge') {
+  const requested = normalizeMethodNames(requestedMethods);
+  if (mode === 'replace') return requested;
+  return normalizeMethodNames([...normalizeMethodNames(existingMethods), ...requested]);
+}
+
+export function summarizeRoutePermission(permission, methodIdNameMap = {}) {
+  return {
+    id: getRecordId(permission),
+    isEnabled: permission?.isEnabled !== false,
+    description: permission?.description || null,
+    route: permission?.route?.path || permission?.route || null,
+    role: permission?.role ? {
+      id: getReferenceId(permission.role),
+      name: permission.role.name || null,
+    } : null,
+    allowedUsers: (permission?.allowedUsers || []).map((user) => ({
+      id: getReferenceId(user),
+      email: user?.email || null,
+    })),
+    methods: permissionMethodNames(permission, methodIdNameMap),
+  };
+}
+
+export function summarizeRouteAccess(route, routePermissions, methodIdNameMap = {}, expected = {}) {
+  const routeId = getRecordId(route);
+  const permissions = (routePermissions || [])
+    .filter((permission) => sameRecordId(getReferenceId(permission?.route), routeId))
+    .map((permission) => summarizeRoutePermission(permission, methodIdNameMap));
+
+  const expectedMethods = normalizeMethodNames(expected.methods || []);
+  const expectedRoleId = expected.roleId ? String(expected.roleId) : null;
+  const expectedAllowedUsers = sortedIdStrings(expected.allowedUserIds || []);
+  const hasExpectedScope = !!(expectedRoleId || expected.roleRequired || expected.allowedUserIds !== undefined);
+  const matchingPermissions = permissions.filter((permission) => {
+    if (!hasExpectedScope) return true;
+    if (expectedRoleId && String(permission.role?.id) !== expectedRoleId) return false;
+    if (!expectedRoleId && expected.roleRequired && permission.role) return false;
+    if (!sameIdSet(permission.allowedUsers.map((user) => user.id), expectedAllowedUsers)) return false;
+    return true;
+  });
+  const grantedMethods = normalizeMethodNames(matchingPermissions.flatMap((permission) => (
+    permission.isEnabled ? permission.methods : []
+  )));
+
+  return {
+    id: routeId,
+    path: route?.path,
+    isEnabled: route?.isEnabled !== false,
+    availableMethods: routeAvailableMethodNames(route, methodIdNameMap),
+    publishedMethods: routePublishedMethodNames(route, methodIdNameMap),
+    skipRoleGuardMethods: methodNamesFromRecords(route?.skipRoleGuardMethods || [], methodIdNameMap),
+    permissions,
+    expected: expectedMethods.length ? {
+      methods: expectedMethods,
+      grantedMethods,
+      missingMethods: expectedMethods.filter((method) => !grantedMethods.includes(method)),
+    } : null,
+  };
+}

package/src/lib/table-tools.js

@@ -16,8 +16,11 @@ const FORBIDDEN_RELATION_KEYS = [
   'fkCol',
   'fkColumn',
   'foreignKeyColumn',
+  'referencedColumn',
+  'constraintName',
   'sourceColumn',
   'targetColumn',
+  'junctionTableName',
   'junctionSourceColumn',
   'junctionTargetColumn',
 ];
@@ -144,6 +147,23 @@ export function normalizeRelationForTablePatch(relation) {
   return normalized;
 }
 
+export function sanitizeExistingRelationForTablePatch(relation) {
+  const {
+    fkCol,
+    fkColumn,
+    foreignKeyColumn,
+    referencedColumn,
+    constraintName,
+    sourceColumn,
+    targetColumn,
+    junctionTableName,
+    junctionSourceColumn,
+    junctionTargetColumn,
+    ...rest
+  } = relation;
+  return normalizeRelationForTablePatch(rest);
+}
+
 export function resolveRelationTargetsFromMetadata(metadata, relations) {
   return relations.map((relation) => {
     const targetTable = relation.targetTable;
@@ -210,7 +230,7 @@ async function verifyRelationCascade(ENFYRA_API_URL, tableId, beforeIds, {
   propertyName,
 }) {
   const tableData = await fetchTableWithDetails(ENFYRA_API_URL, tableId);
-  const afterRelations = (tableData.relations || []).map(normalizeRelationForTablePatch);
+  const afterRelations = (tableData.relations || []).map(sanitizeExistingRelationForTablePatch);
   const afterIds = afterRelations.map((relation) => String(getId(relation))).filter((id) => id !== 'null');
   const excludedIds = action === 'delete' ? [relationId] : [];
   const missingIds = getMissingIds(beforeIds, afterIds, excludedIds);
@@ -293,7 +313,7 @@ export function registerTableTools(server, ENFYRA_API_URL) {
     if (!tableData) {
       return { content: [{ type: 'text', text: `Error: Table with ID ${sourceTableId} not found.` }] };
     }
-    const existingRelations = (tableData.relations || []).map(normalizeRelationForTablePatch);
+    const existingRelations = (tableData.relations || []).map(sanitizeExistingRelationForTablePatch);
     const beforeIds = existingRelations.map((relation) => String(getId(relation))).filter((id) => id !== 'null');
     const newRelation = { targetTable: targetTableId, type, propertyName };
     if (inversePropertyName !== undefined) newRelation.inversePropertyName = inversePropertyName || null;
@@ -361,7 +381,7 @@ export function registerTableTools(server, ENFYRA_API_URL) {
       return { content: [{ type: 'text', text: `Error: Table with ID ${tableId} not found.` }] };
     }
 
-    const existingRelations = (tableData.relations || []).map(normalizeRelationForTablePatch);
+    const existingRelations = (tableData.relations || []).map(sanitizeExistingRelationForTablePatch);
     const beforeIds = existingRelations.map((relation) => String(getId(relation))).filter((id) => id !== 'null');
     if (!beforeIds.includes(String(relationId))) {
       throw new Error(`Relation ${relationId} was not found on table ${tableId}; refusing schema cascade patch.`);

package/src/mcp-server-entry.mjs

@@ -21,6 +21,17 @@ import { getExamples, listExampleCategories } from './lib/mcp-examples.js';
 import { registerTableTools } from './lib/table-tools.js';
 import { prepareRecordMutation, validateScriptSourceIfPresent } from './lib/mutation-guards.js';
 import { validateMainTableRoutePath } from './lib/route-guards.js';
+import {
+  findRoutePermission,
+  mergeMethodNames,
+  normalizeMethodNames,
+  resolveRoleByNameOrId,
+  routeAvailableMethodNames,
+  routePublishedMethodNames,
+  summarizeRouteAccess,
+  summarizeRoutePermission,
+  validateMethodsForRoute,
+} from './lib/route-permission-tools.js';
 
 // Initialize auth module
 initAuth(ENFYRA_API_URL, ENFYRA_API_TOKEN);
@@ -2092,6 +2103,179 @@ server.tool(
   },
 );
 
+server.tool(
+  'audit_route_access',
+  [
+    'Audit route access for one or more routes.',
+    'Use this before granting access or debugging 403s. It reports available methods, public published methods, skipRoleGuard methods, route permissions, and optional missing methods for one role/user scope.',
+  ].join(' '),
+  {
+    path: z.string().optional().describe('Exact route path, e.g. /orders'),
+    routeId: z.union([z.string(), z.number()]).optional().describe('Exact route id'),
+    search: z.string().optional().describe('Optional route path search when path/routeId is not provided'),
+    roleId: z.union([z.string(), z.number()]).optional().describe('Expected role id to check'),
+    roleName: z.string().optional().describe('Expected role name to resolve, e.g. user'),
+    allowedUserIds: z.array(z.union([z.string(), z.number()])).optional().describe('Expected direct/specific user ids to check'),
+    methods: z.array(z.string()).optional().describe('Methods expected to be allowed for this scope'),
+    limit: z.number().int().positive().max(100).optional().default(25).describe('Maximum routes returned for search mode'),
+  },
+  async ({ path, routeId, search, roleId, roleName, allowedUserIds, methods, limit }) => {
+    if ([path, routeId, search].filter((value) => value !== undefined && value !== null && value !== '').length > 1) {
+      throw new Error('Use only one of path, routeId, or search.');
+    }
+    if (roleId && roleName) throw new Error('Provide roleId or roleName, not both.');
+
+    const [routes, routePermissions, roles, methodIdNameMap] = await Promise.all([
+      fetchAll('/route_definition?limit=1000'),
+      fetchAll('/route_permission_definition?limit=1000'),
+      fetchAll('/role_definition?limit=1000'),
+      getMethodIdNameMap(),
+    ]);
+
+    const role = resolveRoleByNameOrId(roles, { roleId, roleName });
+    const normalizedPath = path ? normalizeRestPath(path) : null;
+    const query = search ? String(search).toLowerCase() : null;
+    const matchedRoutes = routes.filter((route) => {
+      if (routeId) return sameId(getId(route), routeId);
+      if (normalizedPath) return route.path === normalizedPath;
+      if (query) return String(route.path || '').toLowerCase().includes(query);
+      return true;
+    }).slice(0, limit);
+
+    const expectedMethods = normalizeMethodNames(methods || []);
+    const payload = {
+      guidance: {
+        publicAccess: 'publishedMethods bypass RoleGuard and do not require route_permission_definition.',
+        authenticatedAccess: 'For non-public methods, eApp PermissionGate and backend RoleGuard both expect enabled route_permission_definition rows with matching route + HTTP method.',
+        directUserAccess: 'allowedRoutePermissions on /me represent direct user-scoped route permissions; role.routePermissions represent role-scoped permissions.',
+      },
+      expectedScope: {
+        role: role ? { id: getId(role), name: role.name } : null,
+        allowedUserIds: allowedUserIds || [],
+        methods: expectedMethods,
+      },
+      returnedRouteCount: matchedRoutes.length,
+      routes: matchedRoutes.map((route) => summarizeRouteAccess(route, routePermissions, methodIdNameMap, {
+        roleId: role ? getId(role) : roleId,
+        roleRequired: !!(role || roleId || roleName),
+        allowedUserIds,
+        methods: expectedMethods,
+      })),
+    };
+
+    return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };
+  },
+);
+
+server.tool(
+  'ensure_route_access',
+  [
+    'Create or update authenticated route access for one role/user scope.',
+    'Use this instead of raw route_permission_definition CRUD when fixing 403s. It resolves roleName/route/method ids, validates route.availableMethods, merges existing permission methods by default, and reloads routes.',
+  ].join(' '),
+  {
+    path: z.string().optional().describe('Route path, e.g. /orders'),
+    routeId: z.union([z.string(), z.number()]).optional().describe('Route id. Use either path or routeId.'),
+    methods: z.array(z.string()).describe('HTTP method names to allow, e.g. ["GET", "POST"].'),
+    roleId: z.union([z.string(), z.number()]).optional().describe('Role id scope'),
+    roleName: z.string().optional().describe('Role name scope, e.g. user. Prefer this when an LLM does not know role ids.'),
+    allowedUserIds: z.array(z.union([z.string(), z.number()])).optional().describe('Specific user ids scope. Omit for role-wide access.'),
+    mode: z.enum(['merge', 'replace']).optional().default('merge').describe('merge adds methods to an existing permission; replace overwrites methods on the matched permission.'),
+    description: z.string().optional().describe('Admin note'),
+    isEnabled: z.boolean().optional().default(true).describe('Enable the permission'),
+  },
+  async ({ path, routeId, methods, roleId, roleName, allowedUserIds, mode, description, isEnabled }) => {
+    if (!path && !routeId) throw new Error('Provide path or routeId.');
+    if (path && routeId) throw new Error('Provide path or routeId, not both.');
+    if (roleId && roleName) throw new Error('Provide roleId or roleName, not both.');
+    if (!roleId && !roleName && (!allowedUserIds || allowedUserIds.length === 0)) {
+      throw new Error('Provide roleId, roleName, or allowedUserIds.');
+    }
+
+    const [routes, routePermissions, roles, methodMap, methodIdNameMap] = await Promise.all([
+      fetchAll('/route_definition?limit=1000'),
+      fetchAll('/route_permission_definition?limit=1000'),
+      fetchAll('/role_definition?limit=1000'),
+      getMethodMap(),
+      getMethodIdNameMap(),
+    ]);
+    const route = routes.find((item) => (
+      routeId ? sameId(getId(item), routeId) : item.path === normalizeRestPath(path)
+    ));
+    if (!route) throw new Error(`Route not found: ${routeId || path}`);
+
+    const role = resolveRoleByNameOrId(roles, { roleId, roleName });
+    const scope = {
+      roleId: role ? getId(role) : roleId,
+      allowedUserIds: allowedUserIds || [],
+    };
+    const requestedMethods = validateMethodsForRoute(route, methods, methodMap, methodIdNameMap);
+    const existing = findRoutePermission(routePermissions, getId(route), scope);
+    const existingMethods = existing ? summarizeRoutePermission(existing, methodIdNameMap).methods : [];
+    const finalMethods = mergeMethodNames(existingMethods, requestedMethods, mode);
+    const methodRefs = resolveMethodIds(methodMap, finalMethods);
+    const publishedMethods = routePublishedMethodNames(route, methodIdNameMap);
+    const alreadyPublic = requestedMethods.filter((method) => publishedMethods.includes(method));
+
+    let result;
+    let action;
+    if (existing) {
+      action = 'updated';
+      const patchBody = {
+        isEnabled,
+        methods: methodRefs,
+        ...(description !== undefined ? { description } : {}),
+      };
+      result = await fetchAPI(ENFYRA_API_URL, `/route_permission_definition/${encodeURIComponent(String(getId(existing)))}`, {
+        method: 'PATCH',
+        body: JSON.stringify(patchBody),
+      });
+    } else {
+      action = 'created';
+      const createBody = {
+        isEnabled,
+        description,
+        route: { id: getId(route) },
+        methods: methodRefs,
+        ...(scope.roleId ? { role: { id: scope.roleId } } : {}),
+        ...(scope.allowedUserIds.length ? { allowedUsers: scope.allowedUserIds.map((id) => ({ id })) } : {}),
+      };
+      result = await fetchAPI(ENFYRA_API_URL, '/route_permission_definition', {
+        method: 'POST',
+        body: JSON.stringify(createBody),
+      });
+    }
+
+    const routeReload = await reloadRoutesResult();
+    const saved = firstDataRecord(result);
+    const payload = {
+      action,
+      kind: 'route_access',
+      route: {
+        id: getId(route),
+        path: route.path,
+        availableMethods: routeAvailableMethodNames(route, methodIdNameMap),
+        publishedMethods,
+      },
+      scope: {
+        role: role ? { id: getId(role), name: role.name } : null,
+        allowedUserIds: scope.allowedUserIds,
+      },
+      permission: {
+        id: getId(saved) || getId(existing),
+        methods: finalMethods,
+        alreadyPublic,
+        isEnabled,
+      },
+      result,
+      routeReload,
+      auditHint: `Call audit_route_access({ path: "${route.path}", ${role ? `roleName: "${role.name}", ` : ''}methods: ${JSON.stringify(requestedMethods)} }) to verify.`,
+    };
+
+    return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };
+  },
+);
+
 server.tool(
   'create_guard',
   [