mirror of
https://github.com/danny-avila/LibreChat.git
synced 2026-11-16 13:00:55 +00:00
📜 feat: Add Skills Discovery and Authoring to the Management API (#15642)
* feat: expose skill discovery and authoring through management API * fix: declare public skill management schema and handler types * fix: preserve skill permissions and shared management error semantics * fix: validate skill file paths before writing storage * test: isolate execution limiter routes from skills management * fix: align skills discovery access and file upload protections * fix: authorize skills operations before sync and upload admission * perf: overlap independent skills authorization reads * style: sort skills management imports
This commit is contained in:
parent
bfaecf131b
commit
8a85df9715
14 changed files with 1094 additions and 78 deletions
|
|
@ -60,6 +60,7 @@ jest.mock('~/server/routes/agents/v1', () => ({
|
|||
}));
|
||||
jest.mock('~/server/routes/agents/openai', () => require('express').Router());
|
||||
jest.mock('~/server/routes/agents/responses', () => require('express').Router());
|
||||
jest.mock('~/server/routes/agents/skills', () => require('express').Router());
|
||||
jest.mock('~/server/routes/agents/management', () => {
|
||||
const router = require('express').Router();
|
||||
router.use((_req, res) => res.status(200).json({ surface: 'management' }));
|
||||
|
|
|
|||
|
|
@ -85,6 +85,8 @@ const mockRequireAgentManagementAuth = jest.fn((req, res, next) => {
|
|||
next();
|
||||
});
|
||||
|
||||
jest.mock('../skills', () => require('express').Router());
|
||||
|
||||
jest.mock('../middleware', () => ({
|
||||
requireAgentManagementAuth: mockRequireAgentManagementAuth,
|
||||
}));
|
||||
|
|
|
|||
67
api/server/routes/agents/__tests__/skills.spec.js
Normal file
67
api/server/routes/agents/__tests__/skills.spec.js
Normal file
|
|
@ -0,0 +1,67 @@
|
|||
const express = require('express');
|
||||
const request = require('supertest');
|
||||
|
||||
const mockList = jest.fn((_req, res) => res.json({ object: 'list' }));
|
||||
const mockWrite = jest.fn((_req, res) => res.json({ saved: true }));
|
||||
const mockSync = jest.fn();
|
||||
const mockIp = jest.fn((_req, _res, next) => next());
|
||||
const mockUser = jest.fn((_req, _res, next) => next());
|
||||
const mockAuth = jest.fn((_req, _res, next) => next());
|
||||
let mockDeps;
|
||||
jest.mock('@librechat/api', () => ({
|
||||
createSkillManagementHandlers: (deps) => {
|
||||
mockDeps = deps;
|
||||
return {
|
||||
list: mockList,
|
||||
get: mockList,
|
||||
update: mockWrite,
|
||||
listFiles: mockList,
|
||||
getFile: mockList,
|
||||
updateFile: mockWrite,
|
||||
};
|
||||
},
|
||||
mapAgentManagementError: () => ({ status: 404, body: { error: { code: 'not_found' } } }),
|
||||
}));
|
||||
jest.mock('../middleware', () => ({ requireAgentManagementAuth: (...args) => mockAuth(...args) }));
|
||||
jest.mock('~/server/middleware', () => ({
|
||||
checkBan: (_req, _res, next) => next(),
|
||||
configMiddleware: (req, _res, next) => {
|
||||
req.config = { tenantConfig: true };
|
||||
next();
|
||||
},
|
||||
}));
|
||||
jest.mock('~/server/middleware/roles/capabilities', () => ({ hasCapability: jest.fn() }));
|
||||
jest.mock('~/server/services/PermissionService', () => ({ checkPermission: jest.fn() }));
|
||||
jest.mock('~/server/services/Skills/handlers', () => ({ getSkillsHandlers: jest.fn() }));
|
||||
jest.mock('~/server/services/Skills/sync', () => ({
|
||||
maybeRunGitHubSkillSyncForRequest: (...args) => mockSync(...args),
|
||||
}));
|
||||
jest.mock('~/server/services/Endpoints/agents/skillDeps', () => ({
|
||||
getSkillDbMethods: () => ({}),
|
||||
getSkillToolDeps: () => ({}),
|
||||
}));
|
||||
jest.mock('~/models', () => ({}));
|
||||
jest.mock('~/server/middleware/limiters/uploadLimiters', () => ({
|
||||
createFileLimiters: () => ({
|
||||
fileUploadIpLimiter: (...args) => mockIp(...args),
|
||||
fileUploadUserLimiter: (...args) => mockUser(...args),
|
||||
}),
|
||||
}));
|
||||
const app = express();
|
||||
app.use(express.json());
|
||||
app.use('/skills', require('../skills'));
|
||||
|
||||
it('wires sync and both upload limiters into the authorized management handlers', async () => {
|
||||
await mockDeps.beforeList({ config: { tenantConfig: true } });
|
||||
expect(mockSync).toHaveBeenCalledWith({ config: { tenantConfig: true } });
|
||||
expect(mockDeps.fileWriteLimiters).toHaveLength(2);
|
||||
const next = jest.fn();
|
||||
for (const limiter of mockDeps.fileWriteLimiters) limiter({}, {}, next);
|
||||
expect(mockIp).toHaveBeenCalledTimes(1);
|
||||
expect(mockUser).toHaveBeenCalledTimes(1);
|
||||
});
|
||||
it('keeps authentication ahead of management handlers', async () => {
|
||||
mockAuth.mockImplementationOnce((_req, res) => res.sendStatus(401));
|
||||
await request(app).get('/skills').expect(401);
|
||||
expect(mockList).not.toHaveBeenCalled();
|
||||
});
|
||||
|
|
@ -55,6 +55,7 @@ const {
|
|||
} = require('~/server/services/Schedules');
|
||||
const responses = require('./responses');
|
||||
const management = require('./management');
|
||||
const skills = require('./skills');
|
||||
const openai = require('./openai');
|
||||
const { v1 } = require('./v1');
|
||||
const chat = require('./chat');
|
||||
|
|
@ -127,6 +128,7 @@ router.use('/v1/responses', responses);
|
|||
* inherit execution authentication or API-key fallback behavior.
|
||||
*/
|
||||
router.use('/v1/agents', management);
|
||||
router.use('/v1/skills', skills);
|
||||
|
||||
/**
|
||||
* OpenAI-compatible API routes (API key authentication handled in route file)
|
||||
|
|
|
|||
40
api/server/routes/agents/skills.js
Normal file
40
api/server/routes/agents/skills.js
Normal file
|
|
@ -0,0 +1,40 @@
|
|||
const express = require('express');
|
||||
const { createSkillManagementHandlers, mapAgentManagementError } = require('@librechat/api');
|
||||
const { createFileLimiters } = require('~/server/middleware/limiters/uploadLimiters');
|
||||
const { maybeRunGitHubSkillSyncForRequest } = require('~/server/services/Skills/sync');
|
||||
const { checkBan, configMiddleware } = require('~/server/middleware');
|
||||
const { hasCapability } = require('~/server/middleware/roles/capabilities');
|
||||
const { checkPermission } = require('~/server/services/PermissionService');
|
||||
const { getSkillsHandlers } = require('~/server/services/Skills/handlers');
|
||||
const {
|
||||
getSkillDbMethods,
|
||||
getSkillToolDeps,
|
||||
} = require('~/server/services/Endpoints/agents/skillDeps');
|
||||
const { getRoleByName } = require('~/models');
|
||||
const { requireAgentManagementAuth } = require('./middleware');
|
||||
|
||||
const router = express.Router();
|
||||
const { fileUploadIpLimiter, fileUploadUserLimiter } = createFileLimiters();
|
||||
const handlers = createSkillManagementHandlers({
|
||||
beforeList: maybeRunGitHubSkillSyncForRequest,
|
||||
fileWriteLimiters: [fileUploadIpLimiter, fileUploadUserLimiter],
|
||||
handlers: getSkillsHandlers(),
|
||||
getSkillById: getSkillDbMethods().getSkillById,
|
||||
getRoleByName,
|
||||
checkPermission,
|
||||
hasCapability,
|
||||
saveFile: getSkillToolDeps().saveSkillFileContent,
|
||||
});
|
||||
router.use(requireAgentManagementAuth, checkBan, configMiddleware);
|
||||
router.get('/', handlers.list);
|
||||
router.get('/:id', handlers.get);
|
||||
router.patch('/:id', handlers.update);
|
||||
router.get('/:id/files', handlers.listFiles);
|
||||
router.get('/:id/files/*relativePath', handlers.getFile);
|
||||
router.put('/:id/files/*relativePath', handlers.updateFile);
|
||||
router.use((_req, res) => {
|
||||
const { status, body } = mapAgentManagementError('not_found');
|
||||
body.error.message = 'Skill or file not found';
|
||||
return res.status(status).json(body);
|
||||
});
|
||||
module.exports = router;
|
||||
|
|
@ -3,7 +3,6 @@ const crypto = require('crypto');
|
|||
const multer = require('multer');
|
||||
const express = require('express');
|
||||
const {
|
||||
createSkillsHandlers,
|
||||
createImportHandler,
|
||||
blockFilteredSkillFile,
|
||||
generateCheckAccess,
|
||||
|
|
@ -11,7 +10,7 @@ const {
|
|||
resolveRequestTenantId,
|
||||
restoreTenantContextFromReq,
|
||||
} = require('@librechat/api');
|
||||
const { isValidObjectIdString, logger } = require('@librechat/data-schemas');
|
||||
const { logger } = require('@librechat/data-schemas');
|
||||
const {
|
||||
PermissionBits,
|
||||
PermissionTypes,
|
||||
|
|
@ -22,30 +21,18 @@ const {
|
|||
const {
|
||||
createSkill,
|
||||
getSkillById,
|
||||
updateSkill,
|
||||
deleteSkill,
|
||||
upsertSkillFile,
|
||||
deleteSkillFile,
|
||||
getSkillFileByPath,
|
||||
getRoleByName,
|
||||
} = require('~/models');
|
||||
const { requireJwtAuth, canAccessSkillResource } = require('~/server/middleware');
|
||||
const {
|
||||
findAccessibleResources,
|
||||
findPubliclyAccessibleResources,
|
||||
hasPublicPermission,
|
||||
grantPermission,
|
||||
} = require('~/server/services/PermissionService');
|
||||
const { grantPermission } = require('~/server/services/PermissionService');
|
||||
const { getStrategyFunctions } = require('~/server/services/Files/strategies');
|
||||
const { createFileLimiters } = require('~/server/middleware/limiters/uploadLimiters');
|
||||
const { maybeRunGitHubSkillSyncForRequest } = require('~/server/services/Skills/sync');
|
||||
const configMiddleware = require('~/server/middleware/config/app');
|
||||
const { getFileStrategy } = require('~/server/utils/getFileStrategy');
|
||||
const {
|
||||
getSkillDbMethods,
|
||||
withDeploymentSkillIds,
|
||||
getSkillStrategyFunctions,
|
||||
} = require('~/server/services/Endpoints/agents/skillDeps');
|
||||
|
||||
const router = express.Router();
|
||||
|
||||
|
|
@ -104,7 +91,6 @@ const checkSkillCreate = generateCheckAccess({
|
|||
// Rate limiters (reuse existing file upload limiters)
|
||||
// ---------------------------------------------------------------------------
|
||||
const { fileUploadIpLimiter, fileUploadUserLimiter } = createFileLimiters();
|
||||
const skillDbMethods = getSkillDbMethods();
|
||||
|
||||
router.use(requireJwtAuth);
|
||||
router.use(configMiddleware);
|
||||
|
|
@ -113,33 +99,8 @@ router.use(checkSkillAccess);
|
|||
// ---------------------------------------------------------------------------
|
||||
// CRUD handlers
|
||||
// ---------------------------------------------------------------------------
|
||||
const handlers = createSkillsHandlers({
|
||||
createSkill,
|
||||
getSkillById: skillDbMethods.getSkillById,
|
||||
listSkillsByAccess: skillDbMethods.listSkillsByAccess,
|
||||
updateSkill,
|
||||
deleteSkill,
|
||||
listSkillFiles: skillDbMethods.listSkillFiles,
|
||||
deleteSkillFile,
|
||||
getSkillFileByPath: skillDbMethods.getSkillFileByPath,
|
||||
updateSkillFileContent: skillDbMethods.updateSkillFileContent,
|
||||
getStrategyFunctions: getSkillStrategyFunctions,
|
||||
findAccessibleResources: async (params) =>
|
||||
params.resourceType === 'skill' && params.requiredPermissions === PermissionBits.VIEW
|
||||
? withDeploymentSkillIds(await findAccessibleResources(params))
|
||||
: findAccessibleResources(params),
|
||||
findPubliclyAccessibleResources: async (params) =>
|
||||
params.resourceType === 'skill' && params.requiredPermissions === PermissionBits.VIEW
|
||||
? withDeploymentSkillIds(await findPubliclyAccessibleResources(params))
|
||||
: findPubliclyAccessibleResources(params),
|
||||
hasPublicPermission: async (params) =>
|
||||
params.resourceType === 'skill' && params.requiredPermissions === PermissionBits.VIEW
|
||||
? withDeploymentSkillIds([]).some((id) => id.toString() === params.resourceId.toString()) ||
|
||||
hasPublicPermission(params)
|
||||
: hasPublicPermission(params),
|
||||
grantPermission,
|
||||
isValidObjectIdString,
|
||||
});
|
||||
const { getSkillsHandlers } = require('~/server/services/Skills/handlers');
|
||||
const handlers = getSkillsHandlers();
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// File storage helper: resolve the active strategy's saveBuffer
|
||||
|
|
|
|||
47
api/server/services/Skills/handlers.js
Normal file
47
api/server/services/Skills/handlers.js
Normal file
|
|
@ -0,0 +1,47 @@
|
|||
const { createSkillsHandlers } = require('@librechat/api');
|
||||
const { isValidObjectIdString } = require('@librechat/data-schemas');
|
||||
const { PermissionBits } = require('librechat-data-provider');
|
||||
const { createSkill, updateSkill, deleteSkill, deleteSkillFile } = require('~/models');
|
||||
const {
|
||||
findAccessibleResources,
|
||||
findPubliclyAccessibleResources,
|
||||
hasPublicPermission,
|
||||
grantPermission,
|
||||
} = require('~/server/services/PermissionService');
|
||||
const {
|
||||
getSkillDbMethods,
|
||||
withDeploymentSkillIds,
|
||||
getSkillStrategyFunctions,
|
||||
} = require('~/server/services/Endpoints/agents/skillDeps');
|
||||
|
||||
function getSkillsHandlers() {
|
||||
const skillDbMethods = getSkillDbMethods();
|
||||
return createSkillsHandlers({
|
||||
createSkill,
|
||||
getSkillById: skillDbMethods.getSkillById,
|
||||
listSkillsByAccess: skillDbMethods.listSkillsByAccess,
|
||||
updateSkill,
|
||||
deleteSkill,
|
||||
listSkillFiles: skillDbMethods.listSkillFiles,
|
||||
deleteSkillFile,
|
||||
getSkillFileByPath: skillDbMethods.getSkillFileByPath,
|
||||
updateSkillFileContent: skillDbMethods.updateSkillFileContent,
|
||||
getStrategyFunctions: getSkillStrategyFunctions,
|
||||
findAccessibleResources: async (params) =>
|
||||
params.resourceType === 'skill' && params.requiredPermissions === PermissionBits.VIEW
|
||||
? withDeploymentSkillIds(await findAccessibleResources(params))
|
||||
: findAccessibleResources(params),
|
||||
findPubliclyAccessibleResources: async (params) =>
|
||||
params.resourceType === 'skill' && params.requiredPermissions === PermissionBits.VIEW
|
||||
? withDeploymentSkillIds(await findPubliclyAccessibleResources(params))
|
||||
: findPubliclyAccessibleResources(params),
|
||||
hasPublicPermission: async (params) =>
|
||||
params.resourceType === 'skill' && params.requiredPermissions === PermissionBits.VIEW
|
||||
? withDeploymentSkillIds([]).some((id) => id.toString() === params.resourceId.toString()) ||
|
||||
hasPublicPermission(params)
|
||||
: hasPublicPermission(params),
|
||||
grantPermission,
|
||||
isValidObjectIdString,
|
||||
});
|
||||
}
|
||||
module.exports = { getSkillsHandlers };
|
||||
46
docs/skills-management-api.md
Normal file
46
docs/skills-management-api.md
Normal file
|
|
@ -0,0 +1,46 @@
|
|||
# Skills management API
|
||||
|
||||
The machine-authenticated Skills surface uses the same `endpoints.agents.managementApi.auth`
|
||||
configuration and client-to-principal bindings as Agent management. It is mounted before the
|
||||
execution router and does not accept browser sessions or execution API keys as fallback.
|
||||
|
||||
| Method | Path | Operation |
|
||||
| ------ | ----------------------------------------------- | --------------------------------------------- |
|
||||
| GET | `/api/agents/v1/skills` | List accessible Skills (`limit` and `cursor`) |
|
||||
| GET | `/api/agents/v1/skills/:id` | Read Skill metadata, body, and frontmatter |
|
||||
| PATCH | `/api/agents/v1/skills/:id` | Update an inline Skill |
|
||||
| GET | `/api/agents/v1/skills/:id/files` | List file metadata |
|
||||
| GET | `/api/agents/v1/skills/:id/files/*relativePath` | Read a file as JSON |
|
||||
| PUT | `/api/agents/v1/skills/:id/files/*relativePath` | Create or replace a text file |
|
||||
|
||||
Skill results expose `id`, configuration fields, `version`, `fileCount`, and ISO timestamps.
|
||||
Ownership, tenant, source metadata, and storage locations are excluded. Skill lists use the Agent
|
||||
management envelope: `object`, `data`, `first_id`, `last_id`, `has_more`, and `after`.
|
||||
Pass returned Skill IDs in the Agent management `skills` field to assign them to an Agent.
|
||||
|
||||
Updates require the version returned by the latest read:
|
||||
|
||||
```json
|
||||
{
|
||||
"expectedVersion": 1,
|
||||
"body": "Updated instructions",
|
||||
"description": "Use this skill when analyzing a new dataset."
|
||||
}
|
||||
```
|
||||
|
||||
Editable fields are `name`, `displayTitle`, `description`, `body`, `frontmatter`, `category`, and
|
||||
`alwaysApply`. Existing Skills validation and content policies apply. Unknown fields are rejected.
|
||||
A stale version returns HTTP 409 with `error.code: "conflict"`; retrieve the current Skill before
|
||||
retrying. Skill reads require VIEW access; updates require EDIT and the Skills USE/CREATE role
|
||||
permissions. Inaccessible and cross-tenant IDs return the same 404 envelope.
|
||||
|
||||
Text-file writes accept `{ "content": "replacement text" }`, capped at 1 MiB of UTF-8 data.
|
||||
Use a relative path such as `references/guide.md`. Absolute paths, traversal, and NUL bytes are
|
||||
rejected. Update `SKILL.md` through the Skill's `body` field with `expectedVersion`, not the file
|
||||
endpoint. File writes use replacement semantics without a version precondition; serialize writers
|
||||
to the same path. After a file write, read the Skill again before a versioned metadata/body update: file writes also
|
||||
increment the parent version. Storage selection stays server-controlled. File JSON reads omit content for
|
||||
binary or oversized files; raw download mode is not supported on this surface.
|
||||
|
||||
Git-synced and deployment-provided Skills are readable but cannot be changed through this API.
|
||||
Change their upstream source instead. Browser routes keep their existing behavior.
|
||||
|
|
@ -77,7 +77,8 @@ export type AgentManagementErrorCode =
|
|||
| 'invalid_request'
|
||||
| 'not_found'
|
||||
| 'permission_denied'
|
||||
| 'internal_error';
|
||||
| 'internal_error'
|
||||
| 'conflict';
|
||||
export type AgentManagementError = {
|
||||
error: {
|
||||
code: AgentManagementErrorCode;
|
||||
|
|
@ -213,6 +214,7 @@ export const agentManagementErrorCodeSchema: z.ZodType<AgentManagementErrorCode>
|
|||
'not_found',
|
||||
'permission_denied',
|
||||
'internal_error',
|
||||
'conflict',
|
||||
]);
|
||||
|
||||
const agentManagementValidationIssueSchema = z
|
||||
|
|
@ -308,6 +310,7 @@ const ERROR_STATUS: Record<AgentManagementErrorCode, number> = {
|
|||
not_found: 404,
|
||||
permission_denied: 403,
|
||||
internal_error: 500,
|
||||
conflict: 409,
|
||||
};
|
||||
|
||||
const ERROR_MESSAGE: Record<AgentManagementErrorCode, string> = {
|
||||
|
|
@ -315,6 +318,7 @@ const ERROR_MESSAGE: Record<AgentManagementErrorCode, string> = {
|
|||
not_found: 'Agent not found',
|
||||
permission_denied: 'Permission denied',
|
||||
internal_error: 'Internal server error',
|
||||
conflict: 'Resource conflict',
|
||||
};
|
||||
|
||||
/** Map known failure classes to a stable envelope without exposing internal error messages. */
|
||||
|
|
|
|||
|
|
@ -26,6 +26,7 @@ import type {
|
|||
CreateSkillResult,
|
||||
UpdateSkillInput,
|
||||
ListSkillsByAccessResult,
|
||||
ListSkillsByAccessParams,
|
||||
UpdateSkillResult,
|
||||
ValidationIssue,
|
||||
} from '@librechat/data-schemas';
|
||||
|
|
@ -34,6 +35,7 @@ import type { Types } from 'mongoose';
|
|||
import type { ServerRequest, StrategyFunctions } from '~/types';
|
||||
import { extractSkillContent, inspectContentWithTraversal } from '~/protection';
|
||||
import { contentFilterBlockResponse } from '~/middleware/contentFilter';
|
||||
import { getDeploymentSkillIds } from './deployment';
|
||||
import { resolveSkillFilePathParam } from './path';
|
||||
import { parseSkillMarkdown } from './parse';
|
||||
import { isBinaryBuffer } from './binary';
|
||||
|
|
@ -53,13 +55,7 @@ export interface SkillsHandlersDeps {
|
|||
/** Skill CRUD — from `@librechat/data-schemas` `createMethods` output. */
|
||||
createSkill: (data: CreateSkillInput) => Promise<CreateSkillResult>;
|
||||
getSkillById: (id: string | Types.ObjectId) => Promise<(ISkill & { _id: Types.ObjectId }) | null>;
|
||||
listSkillsByAccess: (params: {
|
||||
accessibleIds: Types.ObjectId[];
|
||||
category?: string;
|
||||
search?: string;
|
||||
limit: number;
|
||||
cursor?: string | null;
|
||||
}) => Promise<ListSkillsByAccessResult>;
|
||||
listSkillsByAccess: (params: ListSkillsByAccessParams) => Promise<ListSkillsByAccessResult>;
|
||||
updateSkill: (params: {
|
||||
id: string;
|
||||
expectedVersion: number;
|
||||
|
|
@ -303,6 +299,10 @@ function blockFilteredSkillContent(
|
|||
return false;
|
||||
}
|
||||
|
||||
type SkillResponseOptions = { includePublicStatus?: boolean };
|
||||
|
||||
type SkillListOptions = Pick<ListSkillsByAccessParams, 'manageTenantId' | 'limit' | 'cursor'>;
|
||||
|
||||
/**
|
||||
* Factory for the typed Express handlers served at `/api/skills`.
|
||||
* The legacy `api/server/routes/skills.js` imports this, passes in concrete
|
||||
|
|
@ -310,10 +310,10 @@ function blockFilteredSkillContent(
|
|||
* onto the Express router.
|
||||
*/
|
||||
export function createSkillsHandlers(deps: SkillsHandlersDeps): {
|
||||
list: (req: ServerRequest, res: Response) => Promise<Response>;
|
||||
list: (req: ServerRequest, res: Response, options?: SkillListOptions) => Promise<Response>;
|
||||
create: (req: ServerRequest, res: Response) => Promise<Response>;
|
||||
get: (req: ServerRequest, res: Response) => Promise<Response>;
|
||||
patch: (req: ServerRequest, res: Response) => Promise<Response>;
|
||||
get: (req: ServerRequest, res: Response, options?: SkillResponseOptions) => Promise<Response>;
|
||||
patch: (req: ServerRequest, res: Response, options?: SkillResponseOptions) => Promise<Response>;
|
||||
delete: (req: ServerRequest, res: Response) => Promise<Response>;
|
||||
listFiles: (req: ServerRequest, res: Response) => Promise<Response>;
|
||||
downloadFile: (req: ServerRequest, res: Response) => Promise<Response | undefined>;
|
||||
|
|
@ -350,7 +350,7 @@ export function createSkillsHandlers(deps: SkillsHandlersDeps): {
|
|||
}
|
||||
}
|
||||
|
||||
async function listHandler(req: ServerRequest, res: Response) {
|
||||
async function listHandler(req: ServerRequest, res: Response, options?: SkillListOptions) {
|
||||
try {
|
||||
const user = req.user;
|
||||
if (!user || !user.id) {
|
||||
|
|
@ -364,18 +364,20 @@ export function createSkillsHandlers(deps: SkillsHandlersDeps): {
|
|||
};
|
||||
const parsedLimit = parseLimit(limit);
|
||||
|
||||
const [accessibleIds, publicIds] = await Promise.all([
|
||||
findAccessibleResources({
|
||||
userId: user.id,
|
||||
role: user.role,
|
||||
resourceType: ResourceType.SKILL,
|
||||
requiredPermissions: PermissionBits.VIEW,
|
||||
}),
|
||||
findPubliclyAccessibleResources({
|
||||
resourceType: ResourceType.SKILL,
|
||||
requiredPermissions: PermissionBits.VIEW,
|
||||
}),
|
||||
]);
|
||||
const [accessibleIds, publicIds] = options?.manageTenantId
|
||||
? [getDeploymentSkillIds(), []]
|
||||
: await Promise.all([
|
||||
findAccessibleResources({
|
||||
userId: user.id,
|
||||
role: user.role,
|
||||
resourceType: ResourceType.SKILL,
|
||||
requiredPermissions: PermissionBits.VIEW,
|
||||
}),
|
||||
findPubliclyAccessibleResources({
|
||||
resourceType: ResourceType.SKILL,
|
||||
requiredPermissions: PermissionBits.VIEW,
|
||||
}),
|
||||
]);
|
||||
|
||||
const mergedIds = Array.from(
|
||||
new Map([...accessibleIds, ...publicIds].map((id) => [id.toString(), id])).values(),
|
||||
|
|
@ -385,8 +387,10 @@ export function createSkillsHandlers(deps: SkillsHandlersDeps): {
|
|||
accessibleIds: mergedIds,
|
||||
category: typeof category === 'string' && category.length > 0 ? category : undefined,
|
||||
search: typeof search === 'string' && search.length > 0 ? search : undefined,
|
||||
limit: parsedLimit,
|
||||
cursor: typeof cursor === 'string' && cursor.length > 0 ? cursor : null,
|
||||
manageTenantId: options?.manageTenantId,
|
||||
limit: options?.limit ?? parsedLimit,
|
||||
cursor:
|
||||
options?.cursor ?? (typeof cursor === 'string' && cursor.length > 0 ? cursor : null),
|
||||
});
|
||||
|
||||
const publicSet = new Set(publicIds.map((id) => id.toString()));
|
||||
|
|
@ -487,7 +491,7 @@ export function createSkillsHandlers(deps: SkillsHandlersDeps): {
|
|||
}
|
||||
}
|
||||
|
||||
async function getHandler(req: ServerRequest, res: Response) {
|
||||
async function getHandler(req: ServerRequest, res: Response, options?: SkillResponseOptions) {
|
||||
try {
|
||||
const { id } = req.params as { id: string };
|
||||
// The canAccessSkillResource middleware already resolved the skill via
|
||||
|
|
@ -502,7 +506,7 @@ export function createSkillsHandlers(deps: SkillsHandlersDeps): {
|
|||
if (!skill) {
|
||||
return res.status(404).json({ error: 'Skill not found' });
|
||||
}
|
||||
const pub = await isSkillPublic(skill._id);
|
||||
const pub = options?.includePublicStatus === false ? false : await isSkillPublic(skill._id);
|
||||
return res.status(200).json(serializeSkill(skill, pub));
|
||||
} catch (error) {
|
||||
logger.error('[GET /skills/:id] Error fetching skill', error);
|
||||
|
|
@ -510,7 +514,7 @@ export function createSkillsHandlers(deps: SkillsHandlersDeps): {
|
|||
}
|
||||
}
|
||||
|
||||
async function patchHandler(req: ServerRequest, res: Response) {
|
||||
async function patchHandler(req: ServerRequest, res: Response, options?: SkillResponseOptions) {
|
||||
try {
|
||||
const { id } = req.params as { id: string };
|
||||
const body = (req.body ?? {}) as TUpdateSkillPayload & { expectedVersion?: number };
|
||||
|
|
@ -564,7 +568,7 @@ export function createSkillsHandlers(deps: SkillsHandlersDeps): {
|
|||
if (result.status === 'not_found') {
|
||||
return res.status(404).json({ error: 'Skill not found' });
|
||||
}
|
||||
const pub = await isSkillPublic(id);
|
||||
const pub = options?.includePublicStatus === false ? false : await isSkillPublic(id);
|
||||
if (result.status === 'conflict') {
|
||||
const conflict: TSkillConflictResponse = {
|
||||
error: 'skill_version_conflict',
|
||||
|
|
@ -655,7 +659,12 @@ export function createSkillsHandlers(deps: SkillsHandlersDeps): {
|
|||
|
||||
// SKILL.md is the skill body itself, not a SkillFile document
|
||||
if (decodedPath === 'SKILL.md') {
|
||||
const skill = await getSkillById(id);
|
||||
const resolved = (
|
||||
req as ServerRequest & {
|
||||
resourceAccess?: { resourceInfo?: ISkill & { _id: Types.ObjectId } };
|
||||
}
|
||||
).resourceAccess?.resourceInfo;
|
||||
const skill = resolved ?? (await getSkillById(id));
|
||||
if (!skill) {
|
||||
return res.status(404).json({ error: 'Skill not found' });
|
||||
}
|
||||
|
|
|
|||
|
|
@ -8,3 +8,4 @@ export * from './parse';
|
|||
export * from './skillStates';
|
||||
export * from './deployment';
|
||||
export * from './sync';
|
||||
export * from './management';
|
||||
|
|
|
|||
466
packages/api/src/skills/management.spec.ts
Normal file
466
packages/api/src/skills/management.spec.ts
Normal file
|
|
@ -0,0 +1,466 @@
|
|||
/* eslint jest/expect-expect: [warn, { assertFunctionNames: ['expect', '**.expect'] }] */
|
||||
import express from 'express';
|
||||
import request from 'supertest';
|
||||
import mongoose, { Types } from 'mongoose';
|
||||
import { MongoMemoryServer } from 'mongodb-memory-server';
|
||||
import { createModels, createMethods, tenantStorage } from '@librechat/data-schemas';
|
||||
import { PermissionBits, Permissions, PermissionTypes } from 'librechat-data-provider';
|
||||
import type { AllMethods, IRole, IUser } from '@librechat/data-schemas';
|
||||
import type { FiltersConfig } from 'librechat-data-provider';
|
||||
import type { RequestHandler } from 'express';
|
||||
import type { SkillManagementDeps } from './management';
|
||||
import type { ServerRequest } from '~/types';
|
||||
import { createSkillManagementHandlers } from './management';
|
||||
import { createSkillsHandlers } from './handlers';
|
||||
|
||||
const tenantId = 'management-test';
|
||||
const author = new Types.ObjectId();
|
||||
const user = { id: author.toString(), _id: author, role: 'USER', tenantId } as IUser;
|
||||
let server: MongoMemoryServer;
|
||||
let db: AllMethods;
|
||||
let app: express.Express;
|
||||
let skillId: string;
|
||||
let allowEdit: boolean;
|
||||
let allowView: boolean;
|
||||
let allowUse: boolean;
|
||||
let canManage: boolean;
|
||||
let authenticated: boolean;
|
||||
let saveFile: jest.MockedFunction<SkillManagementDeps['saveFile']>;
|
||||
let filters: FiltersConfig | undefined;
|
||||
let readSkill: jest.SpyInstance;
|
||||
let beforeList: jest.Mock;
|
||||
let uploadLimiter: jest.MockedFunction<RequestHandler>;
|
||||
let accessible: jest.Mock;
|
||||
let publiclyAccessible: jest.Mock;
|
||||
let publicStatus: jest.Mock;
|
||||
let capabilityCheck: jest.Mock;
|
||||
let originalStrict: string | undefined;
|
||||
const inTenant = <T>(fn: () => T) => tenantStorage.run({ tenantId }, fn);
|
||||
|
||||
beforeAll(async () => {
|
||||
originalStrict = process.env.TENANT_ISOLATION_STRICT;
|
||||
process.env.TENANT_ISOLATION_STRICT = 'true';
|
||||
server = await MongoMemoryServer.create();
|
||||
await mongoose.connect(server.getUri());
|
||||
createModels(mongoose);
|
||||
db = createMethods(mongoose);
|
||||
});
|
||||
afterAll(async () => {
|
||||
await mongoose.disconnect();
|
||||
await server.stop();
|
||||
if (originalStrict == null) delete process.env.TENANT_ISOLATION_STRICT;
|
||||
else process.env.TENANT_ISOLATION_STRICT = originalStrict;
|
||||
});
|
||||
beforeEach(async () => {
|
||||
await mongoose.connection.dropDatabase();
|
||||
allowEdit = true;
|
||||
allowView = true;
|
||||
allowUse = true;
|
||||
canManage = false;
|
||||
authenticated = true;
|
||||
filters = undefined;
|
||||
readSkill = jest.spyOn(db, 'getSkillById');
|
||||
const { skill } = await inTenant(() =>
|
||||
db.createSkill({
|
||||
name: 'test-skill',
|
||||
description: 'Use this skill to test management operations safely.',
|
||||
body: 'Original instructions',
|
||||
author,
|
||||
authorName: 'Test',
|
||||
tenantId,
|
||||
}),
|
||||
);
|
||||
skillId = skill._id.toString();
|
||||
saveFile = jest.fn(async ({ relativePath, content }) => ({
|
||||
relativePath,
|
||||
bytes: Buffer.byteLength(content),
|
||||
}));
|
||||
beforeList = jest.fn();
|
||||
uploadLimiter = jest.fn((_req, _res, next) => next());
|
||||
accessible = jest.fn(async () => (allowView ? [new Types.ObjectId(skillId)] : []));
|
||||
publiclyAccessible = jest.fn(async () => []);
|
||||
publicStatus = jest.fn(async () => false);
|
||||
capabilityCheck = jest.fn(async () => canManage);
|
||||
const handlers = createSkillsHandlers({
|
||||
...db,
|
||||
findAccessibleResources: accessible,
|
||||
findPubliclyAccessibleResources: publiclyAccessible,
|
||||
hasPublicPermission: publicStatus,
|
||||
grantPermission: async () => undefined,
|
||||
getStrategyFunctions: () => ({}),
|
||||
isValidObjectIdString: (id) => typeof id === 'string' && /^[a-f\d]{24}$/i.test(id),
|
||||
});
|
||||
const management = createSkillManagementHandlers({
|
||||
handlers,
|
||||
beforeList,
|
||||
fileWriteLimiters: [uploadLimiter],
|
||||
getSkillById: db.getSkillById,
|
||||
getRoleByName: async () =>
|
||||
({
|
||||
permissions: {
|
||||
[PermissionTypes.SKILLS]: {
|
||||
[Permissions.USE]: allowUse,
|
||||
[Permissions.CREATE]: true,
|
||||
},
|
||||
},
|
||||
}) as IRole,
|
||||
checkPermission: async ({ requiredPermission }) =>
|
||||
requiredPermission === PermissionBits.EDIT ? allowEdit : allowView,
|
||||
saveFile,
|
||||
hasCapability: capabilityCheck,
|
||||
});
|
||||
app = express();
|
||||
app.use(express.json());
|
||||
app.use((req, _res, next) => {
|
||||
if (authenticated) req.user = user;
|
||||
(req as ServerRequest).config = { filters } as ServerRequest['config'];
|
||||
tenantStorage.run({ tenantId }, next);
|
||||
});
|
||||
app.get('/skills', async (req, res) => {
|
||||
await management.list(req, res);
|
||||
});
|
||||
app.get('/skills/:id', async (req, res) => {
|
||||
await management.get(req, res);
|
||||
});
|
||||
app.patch('/skills/:id', async (req, res) => {
|
||||
await management.update(req, res);
|
||||
});
|
||||
app.get('/skills/:id/files', async (req, res) => {
|
||||
await management.listFiles(req, res);
|
||||
});
|
||||
app.get('/skills/:id/files/*relativePath', async (req, res) => {
|
||||
await management.getFile(req, res);
|
||||
});
|
||||
app.put('/skills/:id/files/*relativePath', async (req, res) => {
|
||||
await management.updateFile(req, res);
|
||||
});
|
||||
});
|
||||
|
||||
it('lists and retrieves stable representations without ownership or storage internals', async () => {
|
||||
const list = await request(app).get('/skills').expect(200);
|
||||
expect(list.body).toMatchObject({
|
||||
object: 'list',
|
||||
first_id: skillId,
|
||||
last_id: skillId,
|
||||
has_more: false,
|
||||
after: null,
|
||||
});
|
||||
expect(list.body.data[0]).toMatchObject({ id: skillId, name: 'test-skill', version: 1 });
|
||||
expect(list.body.data[0]).not.toHaveProperty('body');
|
||||
const detail = await request(app).get(`/skills/${skillId}`).expect(200);
|
||||
expect(detail.body).toMatchObject({ id: skillId, body: 'Original instructions' });
|
||||
for (const key of ['_id', 'tenantId', 'author', 'sourceMetadata', 'source']) {
|
||||
expect(detail.body).not.toHaveProperty(key);
|
||||
expect(list.body.data[0]).not.toHaveProperty(key);
|
||||
}
|
||||
});
|
||||
it('reuses validation and versioned persistence for partial updates', async () => {
|
||||
const updated = await request(app)
|
||||
.patch(`/skills/${skillId}`)
|
||||
.send({ expectedVersion: 1, body: 'Updated instructions' })
|
||||
.expect(200);
|
||||
expect(updated.body).toMatchObject({
|
||||
id: skillId,
|
||||
version: 2,
|
||||
body: 'Updated instructions',
|
||||
name: 'test-skill',
|
||||
});
|
||||
expect(await inTenant(() => db.getSkillById(skillId))).toMatchObject({
|
||||
version: 2,
|
||||
body: 'Updated instructions',
|
||||
});
|
||||
const conflict = await request(app)
|
||||
.patch(`/skills/${skillId}`)
|
||||
.send({ expectedVersion: 1, body: 'Stale writer' })
|
||||
.expect(409);
|
||||
expect(conflict.body).toMatchObject({ error: { code: 'conflict' } });
|
||||
expect(conflict.body).not.toHaveProperty('current');
|
||||
await request(app)
|
||||
.patch(`/skills/${skillId}`)
|
||||
.send({ expectedVersion: 2, name: 'INVALID NAME' })
|
||||
.expect(400);
|
||||
});
|
||||
it.each(['tenantId', 'author', 'source', 'sourceMetadata', 'user', 'permissions'])(
|
||||
'rejects caller-controlled %s',
|
||||
async (key) => {
|
||||
await request(app)
|
||||
.patch(`/skills/${skillId}`)
|
||||
.send({ expectedVersion: 1, body: 'Updated', [key]: 'forged' })
|
||||
.expect(400);
|
||||
expect(await inTenant(() => db.getSkillById(skillId))).toMatchObject({ version: 1 });
|
||||
},
|
||||
);
|
||||
it.each([
|
||||
{ expectedVersion: 0, body: 'x' },
|
||||
{ body: 'x' },
|
||||
{ expectedVersion: 1 },
|
||||
{ expectedVersion: 1, body: null },
|
||||
])('rejects malformed updates %j', async (body) => {
|
||||
await request(app).patch(`/skills/${skillId}`).send(body).expect(400);
|
||||
});
|
||||
it('hides inaccessible and cross-tenant Skills, including on file writes', async () => {
|
||||
allowView = false;
|
||||
allowEdit = false;
|
||||
await request(app).get(`/skills/${skillId}`).expect(404);
|
||||
await request(app)
|
||||
.patch(`/skills/${skillId}`)
|
||||
.send({ expectedVersion: 1, body: 'x' })
|
||||
.expect(404);
|
||||
await request(app)
|
||||
.put(`/skills/${skillId}/files/reference.md`)
|
||||
.send({ content: 'x' })
|
||||
.expect(404);
|
||||
expect(saveFile).not.toHaveBeenCalled();
|
||||
allowView = true;
|
||||
allowEdit = true;
|
||||
const { skill } = await tenantStorage.run({ tenantId: 'foreign' }, () =>
|
||||
db.createSkill({
|
||||
name: 'foreign',
|
||||
description: 'Foreign tenant skill for access isolation tests.',
|
||||
body: 'secret',
|
||||
author,
|
||||
authorName: 'Foreign',
|
||||
tenantId: 'foreign',
|
||||
}),
|
||||
);
|
||||
await request(app).get(`/skills/${skill._id}`).set('x-tenant-id', 'foreign').expect(404);
|
||||
await request(app)
|
||||
.patch(`/skills/${skill._id}`)
|
||||
.send({ expectedVersion: 1, body: 'x' })
|
||||
.expect(404);
|
||||
});
|
||||
it('allows viewing without allowing editing', async () => {
|
||||
allowEdit = false;
|
||||
await request(app).get(`/skills/${skillId}`).expect(200);
|
||||
await request(app)
|
||||
.patch(`/skills/${skillId}`)
|
||||
.send({ expectedVersion: 1, body: 'x' })
|
||||
.expect(404);
|
||||
});
|
||||
it('enforces authentication and the Skills role gate', async () => {
|
||||
authenticated = false;
|
||||
await request(app).get('/skills').expect(403);
|
||||
authenticated = true;
|
||||
allowUse = false;
|
||||
await request(app).get('/skills').expect(403);
|
||||
});
|
||||
it('keeps synchronized Skill content and files read-only', async () => {
|
||||
await inTenant(() =>
|
||||
db.updateSkill({ id: skillId, expectedVersion: 1, update: { source: 'github' } }),
|
||||
);
|
||||
await request(app).get(`/skills/${skillId}`).expect(200);
|
||||
await request(app)
|
||||
.patch(`/skills/${skillId}`)
|
||||
.send({ expectedVersion: 2, body: 'x' })
|
||||
.expect(403);
|
||||
await request(app)
|
||||
.put(`/skills/${skillId}/files/reference.md`)
|
||||
.send({ content: 'x' })
|
||||
.expect(403);
|
||||
expect(saveFile).not.toHaveBeenCalled();
|
||||
});
|
||||
it('writes nested text files through existing storage and rejects unsafe paths', async () => {
|
||||
await request(app)
|
||||
.put(`/skills/${skillId}/files/references/guide.md`)
|
||||
.send({ content: 'Guide' })
|
||||
.expect(200);
|
||||
expect(saveFile).toHaveBeenCalledWith(
|
||||
expect.objectContaining({
|
||||
skillId,
|
||||
relativePath: 'references/guide.md',
|
||||
content: 'Guide',
|
||||
mimeType: 'text/plain',
|
||||
}),
|
||||
);
|
||||
saveFile.mockClear();
|
||||
for (const path of [
|
||||
'SKILL.md',
|
||||
'SKILL.md/child.md',
|
||||
'..%2Fescape.md',
|
||||
'bad%5Cpath.md',
|
||||
'x'.repeat(1025),
|
||||
]) {
|
||||
await request(app).put(`/skills/${skillId}/files/${path}`).send({ content: 'x' }).expect(400);
|
||||
}
|
||||
expect(saveFile).not.toHaveBeenCalled();
|
||||
});
|
||||
it('rejects raw downloads and malformed pagination', async () => {
|
||||
await request(app).get(`/skills/${skillId}/files/SKILL.md?raw=true`).expect(400);
|
||||
await request(app).get('/skills?limit=0').expect(400);
|
||||
await request(app).get('/skills?cursor=garbage').expect(400);
|
||||
await request(app).get('/skills?tenantId=foreign').expect(400);
|
||||
});
|
||||
|
||||
it('preserves the resource-management capability without bypassing tenant isolation', async () => {
|
||||
allowEdit = false;
|
||||
canManage = true;
|
||||
allowView = false;
|
||||
const response = await request(app)
|
||||
.patch(`/skills/${skillId}`)
|
||||
.send({ expectedVersion: 1, body: 'Managed update' })
|
||||
.expect(200);
|
||||
expect(response.body.body).toBe('Managed update');
|
||||
const { skill } = await tenantStorage.run({ tenantId: 'foreign' }, () =>
|
||||
db.createSkill({
|
||||
name: 'foreign',
|
||||
description: 'Foreign tenant skill for capability isolation tests.',
|
||||
body: 'secret',
|
||||
author,
|
||||
authorName: 'Foreign',
|
||||
tenantId: 'foreign',
|
||||
}),
|
||||
);
|
||||
await request(app)
|
||||
.patch(`/skills/${skill._id}`)
|
||||
.send({ expectedVersion: 1, body: 'x' })
|
||||
.expect(404);
|
||||
const list = await request(app).get('/skills').expect(200);
|
||||
expect(list.body.data.map((row: { id: string }) => row.id)).toEqual([skillId]);
|
||||
canManage = false;
|
||||
const denied = await request(app).get('/skills').expect(200);
|
||||
expect(denied.body.data).toEqual([]);
|
||||
});
|
||||
|
||||
it('reuses the authorized Skill on detail reads', async () => {
|
||||
await request(app).get(`/skills/${skillId}`).expect(200);
|
||||
expect(readSkill).toHaveBeenCalledTimes(1);
|
||||
});
|
||||
it('classifies content-policy blocks as invalid input and never writes the file', async () => {
|
||||
filters = {
|
||||
skills: {
|
||||
pii: {
|
||||
fields: ['file_text'],
|
||||
starterPatterns: [],
|
||||
customPatterns: [{ id: 'private', label: 'private text', regex: 'PRIVATE-TEXT' }],
|
||||
},
|
||||
},
|
||||
};
|
||||
const result = await request(app)
|
||||
.put(`/skills/${skillId}/files/notes.md`)
|
||||
.send({ content: 'PRIVATE-TEXT' })
|
||||
.expect(400);
|
||||
expect(result.body).toMatchObject({ error: { code: 'invalid_request' } });
|
||||
expect(saveFile).not.toHaveBeenCalled();
|
||||
});
|
||||
it('returns safe errors for storage failures', async () => {
|
||||
saveFile.mockRejectedValueOnce(new Error('secret-storage-path'));
|
||||
const result = await request(app)
|
||||
.put(`/skills/${skillId}/files/notes.md`)
|
||||
.send({ content: 'Notes' })
|
||||
.expect(500);
|
||||
expect(result.body).toEqual({
|
||||
error: { code: 'internal_error', message: 'Internal server error' },
|
||||
});
|
||||
});
|
||||
|
||||
it('reuses the authorized Skill for SKILL.md reads', async () => {
|
||||
const response = await request(app).get(`/skills/${skillId}/files/SKILL.md`).expect(200);
|
||||
expect(response.body.content).toBe('Original instructions');
|
||||
expect(readSkill).toHaveBeenCalledTimes(1);
|
||||
});
|
||||
it.each(['1e2', '0x10'])('honors normalized pagination for limit=%s', async (limit) => {
|
||||
canManage = true;
|
||||
await inTenant(() =>
|
||||
db.createSkill({
|
||||
name: 'second-skill',
|
||||
description: 'Second skill for pagination validation.',
|
||||
body: 'Instructions',
|
||||
author,
|
||||
authorName: 'Test',
|
||||
tenantId,
|
||||
}),
|
||||
);
|
||||
const response = await request(app).get(`/skills?limit=${limit}`).expect(200);
|
||||
expect(response.body.data).toHaveLength(2);
|
||||
});
|
||||
|
||||
it('authorizes and validates discovery before starting sync', async () => {
|
||||
allowUse = false;
|
||||
await request(app).get('/skills').expect(403);
|
||||
expect(beforeList).not.toHaveBeenCalled();
|
||||
allowUse = true;
|
||||
await request(app).get('/skills?limit=0').expect(400);
|
||||
expect(beforeList).not.toHaveBeenCalled();
|
||||
await request(app).get('/skills').expect(200);
|
||||
expect(beforeList).toHaveBeenCalledTimes(1);
|
||||
expect(beforeList.mock.invocationCallOrder[0]).toBeLessThan(
|
||||
accessible.mock.invocationCallOrder[0],
|
||||
);
|
||||
});
|
||||
it('continues discovery after a sync trigger failure', async () => {
|
||||
beforeList.mockRejectedValueOnce(new Error('sync unavailable'));
|
||||
await request(app).get('/skills').expect(200);
|
||||
expect(accessible).toHaveBeenCalledTimes(1);
|
||||
});
|
||||
it('does not enumerate ACLs for capability-managed lists', async () => {
|
||||
canManage = true;
|
||||
await request(app).get('/skills').expect(200);
|
||||
expect(accessible).not.toHaveBeenCalled();
|
||||
expect(publiclyAccessible).not.toHaveBeenCalled();
|
||||
});
|
||||
it('does not read discarded public status for details, updates, or conflicts', async () => {
|
||||
await request(app).get(`/skills/${skillId}`).expect(200);
|
||||
await request(app)
|
||||
.patch(`/skills/${skillId}`)
|
||||
.send({ expectedVersion: 1, body: 'Updated' })
|
||||
.expect(200);
|
||||
await request(app)
|
||||
.patch(`/skills/${skillId}`)
|
||||
.send({ expectedVersion: 1, body: 'Stale' })
|
||||
.expect(409);
|
||||
expect(publicStatus).not.toHaveBeenCalled();
|
||||
});
|
||||
it('authorizes file targets before charging upload quotas', async () => {
|
||||
allowUse = false;
|
||||
await request(app).put(`/skills/${skillId}/files/note.txt`).send({ content: 'text' }).expect(403);
|
||||
allowUse = true;
|
||||
allowEdit = false;
|
||||
await request(app).put(`/skills/${skillId}/files/note.txt`).send({ content: 'text' }).expect(404);
|
||||
allowEdit = true;
|
||||
await request(app)
|
||||
.put(`/skills/${new Types.ObjectId()}/files/note.txt`)
|
||||
.send({ content: 'text' })
|
||||
.expect(404);
|
||||
expect(uploadLimiter).not.toHaveBeenCalled();
|
||||
expect(saveFile).not.toHaveBeenCalled();
|
||||
await request(app).put(`/skills/${skillId}/files/note.txt`).send({ content: 'text' }).expect(200);
|
||||
expect(uploadLimiter).toHaveBeenCalledTimes(1);
|
||||
expect(readSkill).toHaveBeenCalledTimes(3);
|
||||
});
|
||||
it('stops storage writes when the upload limiter rejects', async () => {
|
||||
uploadLimiter.mockImplementationOnce((_req, res) => {
|
||||
res.sendStatus(429);
|
||||
});
|
||||
await request(app).put(`/skills/${skillId}/files/note.txt`).send({ content: 'text' }).expect(429);
|
||||
expect(saveFile).not.toHaveBeenCalled();
|
||||
});
|
||||
it('fails closed when the upload limiter errors', async () => {
|
||||
uploadLimiter.mockImplementationOnce((_req, _res, next) => next(new Error('limiter failure')));
|
||||
await request(app).put(`/skills/${skillId}/files/note.txt`).send({ content: 'text' }).expect(500);
|
||||
expect(saveFile).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('starts independent capability checks while waiting for the tenant-scoped Skill', async () => {
|
||||
let releaseSkill!: (value: null) => void;
|
||||
let capabilityStarted!: () => void;
|
||||
const started = new Promise<void>((resolve) => {
|
||||
capabilityStarted = resolve;
|
||||
});
|
||||
readSkill.mockImplementationOnce(
|
||||
() =>
|
||||
new Promise((resolve) => {
|
||||
releaseSkill = resolve;
|
||||
}),
|
||||
);
|
||||
capabilityCheck.mockImplementationOnce(async () => {
|
||||
capabilityStarted();
|
||||
return true;
|
||||
});
|
||||
const response = request(app)
|
||||
.get(`/skills/${skillId}`)
|
||||
.then((result) => result);
|
||||
await started;
|
||||
expect(readSkill).toHaveBeenCalledTimes(1);
|
||||
releaseSkill(null);
|
||||
expect((await response).status).toBe(404);
|
||||
});
|
||||
365
packages/api/src/skills/management.ts
Normal file
365
packages/api/src/skills/management.ts
Normal file
|
|
@ -0,0 +1,365 @@
|
|||
import { z } from 'zod';
|
||||
import { logger, ResourceCapabilityMap, validateRelativePath } from '@librechat/data-schemas';
|
||||
import {
|
||||
PermissionBits,
|
||||
Permissions,
|
||||
PermissionTypes,
|
||||
ResourceType,
|
||||
} from 'librechat-data-provider';
|
||||
import type { SkillFrontmatterValue, TSkill, TUpdateSkillPayload } from 'librechat-data-provider';
|
||||
import type { Request, Response, RequestHandler } from 'express';
|
||||
import type { SkillsHandlers, SkillsHandlersDeps } from './handlers';
|
||||
import type { AgentManagementReadDeps } from '../agents/reads';
|
||||
import type { ServerRequest } from '~/types';
|
||||
import { agentManagementListSchema, mapAgentManagementError } from '../agents/management';
|
||||
import { isContentFilterError } from '../middleware/contentFilter';
|
||||
import { checkAccessWithRequestCache } from '../middleware/access';
|
||||
import { assertSkillFileContentAllowed } from './protection';
|
||||
import { getDeploymentSkillById } from './deployment';
|
||||
import { resolveSkillFilePathParam } from './path';
|
||||
|
||||
const idSchema = z.string().regex(/^[a-f\d]{24}$/i);
|
||||
const fields = {
|
||||
name: z.string(),
|
||||
displayTitle: z.string().optional(),
|
||||
description: z.string(),
|
||||
category: z.string().optional(),
|
||||
alwaysApply: z.boolean().optional(),
|
||||
};
|
||||
const frontmatterValue: z.ZodType<SkillFrontmatterValue> = z.lazy(() =>
|
||||
z.union([
|
||||
z.string(),
|
||||
z.number().finite(),
|
||||
z.boolean(),
|
||||
z.null(),
|
||||
z.array(frontmatterValue),
|
||||
z.record(frontmatterValue),
|
||||
]),
|
||||
);
|
||||
export type SkillManagementUpdate = TUpdateSkillPayload & { expectedVersion: number };
|
||||
|
||||
export const skillManagementUpdateSchema: z.ZodType<SkillManagementUpdate> = z
|
||||
.object({
|
||||
name: fields.name.optional(),
|
||||
displayTitle: fields.displayTitle,
|
||||
description: fields.description.optional(),
|
||||
category: fields.category,
|
||||
alwaysApply: fields.alwaysApply,
|
||||
body: z.string().optional(),
|
||||
frontmatter: z.record(frontmatterValue).optional(),
|
||||
expectedVersion: z.number().int().positive(),
|
||||
})
|
||||
.strict()
|
||||
.refine((value) => Object.keys(value).length > 1, 'At least one update field is required');
|
||||
|
||||
const summarySchema = z.object({
|
||||
...fields,
|
||||
id: idSchema,
|
||||
version: z.number().int().positive(),
|
||||
fileCount: z.number().int().nonnegative(),
|
||||
disableModelInvocation: z.boolean().optional(),
|
||||
userInvocable: z.boolean().optional(),
|
||||
allowedTools: z.array(z.string()).optional(),
|
||||
createdAt: z.string().datetime(),
|
||||
updatedAt: z.string().datetime(),
|
||||
});
|
||||
export type SkillManagementResponse = Pick<
|
||||
TSkill,
|
||||
| 'name'
|
||||
| 'displayTitle'
|
||||
| 'description'
|
||||
| 'category'
|
||||
| 'alwaysApply'
|
||||
| 'version'
|
||||
| 'fileCount'
|
||||
| 'disableModelInvocation'
|
||||
| 'userInvocable'
|
||||
| 'allowedTools'
|
||||
| 'createdAt'
|
||||
| 'updatedAt'
|
||||
| 'body'
|
||||
| 'frontmatter'
|
||||
> & { id: string };
|
||||
|
||||
export const skillManagementResponseSchema: z.ZodType<SkillManagementResponse> =
|
||||
summarySchema.extend({
|
||||
body: z.string(),
|
||||
frontmatter: z.record(frontmatterValue).optional(),
|
||||
});
|
||||
const fileSchema = z.object({
|
||||
relativePath: z.string(),
|
||||
filename: z.string(),
|
||||
mimeType: z.string(),
|
||||
bytes: z.number().int().nonnegative(),
|
||||
});
|
||||
const fileContentSchema = fileSchema.extend({
|
||||
content: z.string().optional(),
|
||||
isBinary: z.boolean(),
|
||||
});
|
||||
const fileUpdateSchema = z.object({ content: z.string().max(1024 * 1024) }).strict();
|
||||
const listSchema = agentManagementListSchema;
|
||||
|
||||
type ManagementRequest = Request &
|
||||
Pick<ServerRequest, 'user' | 'config'> & {
|
||||
resourceAccess?: {
|
||||
resourceInfo: NonNullable<Awaited<ReturnType<SkillsHandlersDeps['getSkillById']>>>;
|
||||
};
|
||||
};
|
||||
|
||||
type SkillHandler = (req: ServerRequest, res: Response) => Promise<Response | undefined>;
|
||||
type Projector = (body: unknown) => object;
|
||||
export interface SkillManagementDeps {
|
||||
handlers: SkillsHandlers;
|
||||
beforeList?: (req: ServerRequest) => Promise<void>;
|
||||
fileWriteLimiters?: RequestHandler[];
|
||||
getSkillById: SkillsHandlersDeps['getSkillById'];
|
||||
getRoleByName: AgentManagementReadDeps['getRoleByName'];
|
||||
checkPermission: AgentManagementReadDeps['checkPermission'];
|
||||
hasCapability: AgentManagementReadDeps['hasCapability'];
|
||||
saveFile: (input: {
|
||||
req: ServerRequest;
|
||||
skillId: string;
|
||||
relativePath: string;
|
||||
content: string;
|
||||
mimeType: string;
|
||||
}) => Promise<{ relativePath: string; bytes: number }>;
|
||||
}
|
||||
|
||||
function projectSkill(body: unknown, detail: boolean): object {
|
||||
const source = z.object({ _id: idSchema }).passthrough().parse(body);
|
||||
return (detail ? skillManagementResponseSchema : summarySchema).parse({
|
||||
...source,
|
||||
id: source._id,
|
||||
});
|
||||
}
|
||||
function sendError(
|
||||
res: Response,
|
||||
code: Parameters<typeof mapAgentManagementError>[0],
|
||||
error?: unknown,
|
||||
) {
|
||||
const mapped = mapAgentManagementError(code, error);
|
||||
if (code === 'not_found') mapped.body.error.message = 'Skill or file not found';
|
||||
return res.status(mapped.status).json(mapped.body);
|
||||
}
|
||||
|
||||
/** Keep browser errors and persistence fields behind the versioned management contract. */
|
||||
async function runHandler(
|
||||
req: ManagementRequest,
|
||||
res: Response,
|
||||
handler: SkillHandler,
|
||||
project: Projector,
|
||||
) {
|
||||
let status = 200;
|
||||
let sent = false;
|
||||
const adapter = Object.create(res) as Response;
|
||||
adapter.status = (value: number) => {
|
||||
status = value;
|
||||
return adapter;
|
||||
};
|
||||
adapter.json = (body: unknown) => {
|
||||
sent = true;
|
||||
if (status >= 200 && status < 300) return res.status(status).json(project(body));
|
||||
if (status === 409) return sendError(res, 'conflict');
|
||||
if (status === 404) return sendError(res, 'not_found');
|
||||
if (status === 400) return sendError(res, 'invalid_request');
|
||||
if (status === 401 || status === 403) return sendError(res, 'permission_denied');
|
||||
return sendError(res, 'internal_error');
|
||||
};
|
||||
await handler(req as ServerRequest, adapter);
|
||||
return sent ? res : sendError(res, 'internal_error');
|
||||
}
|
||||
|
||||
/** Wait for limiter admission or a terminal response; release listeners on every outcome. */
|
||||
async function admitFileWrite(req: Request, res: Response, limiters: RequestHandler[]) {
|
||||
for (const limiter of limiters) {
|
||||
const admitted = await new Promise<boolean>((resolve, reject) => {
|
||||
const finish = () => settle(false);
|
||||
const settle = (allowed: boolean, error?: unknown) => {
|
||||
res.off('finish', finish);
|
||||
res.off('close', finish);
|
||||
if (error) reject(error);
|
||||
else resolve(allowed);
|
||||
};
|
||||
if (res.writableEnded || res.destroyed) return settle(false);
|
||||
res.once('finish', finish);
|
||||
res.once('close', finish);
|
||||
try {
|
||||
Promise.resolve(limiter(req, res, (error) => settle(!error, error))).catch((error) =>
|
||||
settle(false, error),
|
||||
);
|
||||
} catch (error) {
|
||||
settle(false, error);
|
||||
}
|
||||
});
|
||||
if (!admitted) return false;
|
||||
}
|
||||
return !res.writableEnded && !res.destroyed;
|
||||
}
|
||||
|
||||
/** Machine API adapters reuse the browser Skills behavior after principal and resource checks. */
|
||||
export function createSkillManagementHandlers(
|
||||
deps: SkillManagementDeps,
|
||||
): Record<
|
||||
'list' | 'get' | 'update' | 'listFiles' | 'getFile' | 'updateFile',
|
||||
(request: Request, res: Response) => Promise<Response>
|
||||
> {
|
||||
async function canManageSkills(req: ManagementRequest): Promise<boolean> {
|
||||
if (!req.user) return false;
|
||||
const capability = ResourceCapabilityMap[ResourceType.SKILL];
|
||||
try {
|
||||
return capability != null && (await deps.hasCapability(req.user, capability));
|
||||
} catch {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
function wrap(
|
||||
permission: PermissionBits | undefined,
|
||||
operation: (req: ManagementRequest, res: Response) => Promise<Response>,
|
||||
) {
|
||||
return async (request: Request, res: Response): Promise<Response> => {
|
||||
const req = request as ManagementRequest;
|
||||
try {
|
||||
if (!req.user?.id || !req.user.tenantId) return sendError(res, 'permission_denied');
|
||||
const editing = permission === PermissionBits.EDIT;
|
||||
const allowed = await checkAccessWithRequestCache({
|
||||
req,
|
||||
user: req.user,
|
||||
permissionType: PermissionTypes.SKILLS,
|
||||
permissions: editing ? [Permissions.USE, Permissions.CREATE] : [Permissions.USE],
|
||||
getRoleByName: deps.getRoleByName,
|
||||
});
|
||||
if (!allowed) return sendError(res, 'permission_denied');
|
||||
if (permission !== undefined) {
|
||||
if (!idSchema.safeParse(req.params.id).success) return sendError(res, 'not_found');
|
||||
const [skill, canManage] = await Promise.all([
|
||||
deps.getSkillById(req.params.id),
|
||||
canManageSkills(req),
|
||||
]);
|
||||
const deployment = getDeploymentSkillById(req.params.id);
|
||||
if (!skill || (!deployment && skill.tenantId !== req.user.tenantId))
|
||||
return sendError(res, 'not_found');
|
||||
if (
|
||||
!deployment &&
|
||||
!canManage &&
|
||||
!(await deps.checkPermission({
|
||||
userId: req.user.id,
|
||||
role: req.user.role,
|
||||
resourceType: ResourceType.SKILL,
|
||||
resourceId: skill._id,
|
||||
requiredPermission: permission,
|
||||
}))
|
||||
)
|
||||
return sendError(res, 'not_found');
|
||||
if (editing && (deployment || skill.source !== 'inline'))
|
||||
return sendError(res, 'permission_denied');
|
||||
req.resourceAccess = { resourceInfo: skill };
|
||||
}
|
||||
return await operation(req, res);
|
||||
} catch (error) {
|
||||
logger.error('[SkillManagement] Request failed', error);
|
||||
return sendError(res, 'internal_error');
|
||||
}
|
||||
};
|
||||
}
|
||||
return {
|
||||
list: wrap(undefined, async (req, res) => {
|
||||
const parsed = listSchema.safeParse(req.query);
|
||||
if (!parsed.success) return sendError(res, 'invalid_request', parsed.error);
|
||||
try {
|
||||
await deps.beforeList?.(req as ServerRequest);
|
||||
} catch (error) {
|
||||
logger.error('[SkillManagement] Failed to start request-scoped skill sync', error);
|
||||
}
|
||||
const manageTenantId = (await canManageSkills(req)) ? req.user?.tenantId : undefined;
|
||||
return runHandler(
|
||||
req,
|
||||
res,
|
||||
(request, response) =>
|
||||
deps.handlers.list(request, response, {
|
||||
...parsed.data,
|
||||
manageTenantId,
|
||||
}),
|
||||
(body) => {
|
||||
const result = z
|
||||
.object({
|
||||
skills: z.array(z.unknown()),
|
||||
has_more: z.boolean(),
|
||||
after: z.string().nullable(),
|
||||
})
|
||||
.parse(body);
|
||||
const data = result.skills.map((skill) => projectSkill(skill, false));
|
||||
const ids = result.skills.map((skill) => z.object({ _id: idSchema }).parse(skill)._id);
|
||||
return {
|
||||
object: 'list',
|
||||
data,
|
||||
first_id: ids[0] ?? null,
|
||||
last_id: ids[ids.length - 1] ?? null,
|
||||
has_more: result.has_more,
|
||||
after: result.after,
|
||||
};
|
||||
},
|
||||
);
|
||||
}),
|
||||
get: wrap(PermissionBits.VIEW, (req, res) =>
|
||||
runHandler(
|
||||
req,
|
||||
res,
|
||||
(request, response) => deps.handlers.get(request, response, { includePublicStatus: false }),
|
||||
(body) => projectSkill(body, true),
|
||||
),
|
||||
),
|
||||
update: wrap(PermissionBits.EDIT, async (req, res) => {
|
||||
const parsed = skillManagementUpdateSchema.safeParse(req.body);
|
||||
if (!parsed.success) return sendError(res, 'invalid_request', parsed.error);
|
||||
req.body = parsed.data;
|
||||
return runHandler(
|
||||
req,
|
||||
res,
|
||||
(request, response) =>
|
||||
deps.handlers.patch(request, response, { includePublicStatus: false }),
|
||||
(body) => projectSkill(body, true),
|
||||
);
|
||||
}),
|
||||
listFiles: wrap(PermissionBits.VIEW, (req, res) =>
|
||||
runHandler(req, res, deps.handlers.listFiles, (body) => ({
|
||||
object: 'list',
|
||||
data: z.object({ files: z.array(fileSchema) }).parse(body).files,
|
||||
})),
|
||||
),
|
||||
getFile: wrap(PermissionBits.VIEW, async (req, res) => {
|
||||
if (Object.keys(req.query).length > 0) return sendError(res, 'invalid_request');
|
||||
return runHandler(req, res, deps.handlers.downloadFile, (body) =>
|
||||
fileContentSchema.parse(body),
|
||||
);
|
||||
}),
|
||||
updateFile: wrap(PermissionBits.EDIT, async (req, res) => {
|
||||
const parsed = fileUpdateSchema.safeParse(req.body);
|
||||
if (!parsed.success) return sendError(res, 'invalid_request', parsed.error);
|
||||
const relativePath = resolveSkillFilePathParam(req.params.relativePath);
|
||||
if (relativePath == null || validateRelativePath(relativePath).length > 0)
|
||||
return sendError(res, 'invalid_request');
|
||||
const buffer = Buffer.from(parsed.data.content, 'utf8');
|
||||
if (buffer.length > 1024 * 1024 || buffer.includes(0))
|
||||
return sendError(res, 'invalid_request');
|
||||
try {
|
||||
assertSkillFileContentAllowed(req.config?.filters, {
|
||||
buffer,
|
||||
originalName: relativePath,
|
||||
relativePath,
|
||||
});
|
||||
} catch (error) {
|
||||
if (!isContentFilterError(error)) throw error;
|
||||
return sendError(res, 'invalid_request');
|
||||
}
|
||||
if (!(await admitFileWrite(req, res, deps.fileWriteLimiters ?? []))) return res;
|
||||
const result = await deps.saveFile({
|
||||
req: req as ServerRequest,
|
||||
skillId: req.params.id,
|
||||
relativePath,
|
||||
content: parsed.data.content,
|
||||
mimeType: 'text/plain',
|
||||
});
|
||||
return res.status(200).json({ relativePath: result.relativePath, bytes: result.bytes });
|
||||
}),
|
||||
};
|
||||
}
|
||||
|
|
@ -751,6 +751,8 @@ export type UpsertSkillFileInput = {
|
|||
};
|
||||
|
||||
export type ListSkillsByAccessParams = {
|
||||
/** Trusted capability-authorized tenant scope; never accept directly from client input. */
|
||||
manageTenantId?: string;
|
||||
accessibleIds: Types.ObjectId[];
|
||||
category?: string;
|
||||
search?: string;
|
||||
|
|
@ -1093,11 +1095,14 @@ export function createSkillMethods(
|
|||
const { ObjectId } = mongoose.Types;
|
||||
|
||||
function buildSkillFilter(
|
||||
params: Pick<ListSkillsByAccessParams, 'accessibleIds' | 'category' | 'search'>,
|
||||
params: Pick<
|
||||
ListSkillsByAccessParams,
|
||||
'accessibleIds' | 'category' | 'search' | 'manageTenantId'
|
||||
>,
|
||||
): FilterQuery<ISkillDocument> {
|
||||
const filter: FilterQuery<ISkillDocument> = {
|
||||
_id: { $in: params.accessibleIds },
|
||||
};
|
||||
const filter: FilterQuery<ISkillDocument> = params.manageTenantId
|
||||
? { tenantId: params.manageTenantId }
|
||||
: { _id: { $in: params.accessibleIds } };
|
||||
if (params.category && params.category.length > 0) {
|
||||
filter.category = params.category;
|
||||
}
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue