diff --git a/api/server/routes/agents/__tests__/idempotencyLimiter.spec.js b/api/server/routes/agents/__tests__/idempotencyLimiter.spec.js index 51c422c8df..cccbacd539 100644 --- a/api/server/routes/agents/__tests__/idempotencyLimiter.spec.js +++ b/api/server/routes/agents/__tests__/idempotencyLimiter.spec.js @@ -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' })); diff --git a/api/server/routes/agents/__tests__/management.spec.js b/api/server/routes/agents/__tests__/management.spec.js index 5d1e244103..3a705ef169 100644 --- a/api/server/routes/agents/__tests__/management.spec.js +++ b/api/server/routes/agents/__tests__/management.spec.js @@ -85,6 +85,8 @@ const mockRequireAgentManagementAuth = jest.fn((req, res, next) => { next(); }); +jest.mock('../skills', () => require('express').Router()); + jest.mock('../middleware', () => ({ requireAgentManagementAuth: mockRequireAgentManagementAuth, })); diff --git a/api/server/routes/agents/__tests__/skills.spec.js b/api/server/routes/agents/__tests__/skills.spec.js new file mode 100644 index 0000000000..6cca03c759 --- /dev/null +++ b/api/server/routes/agents/__tests__/skills.spec.js @@ -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(); +}); diff --git a/api/server/routes/agents/index.js b/api/server/routes/agents/index.js index f3bdd73c75..21e119362e 100644 --- a/api/server/routes/agents/index.js +++ b/api/server/routes/agents/index.js @@ -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) diff --git a/api/server/routes/agents/skills.js b/api/server/routes/agents/skills.js new file mode 100644 index 0000000000..ccace9bf8b --- /dev/null +++ b/api/server/routes/agents/skills.js @@ -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; diff --git a/api/server/routes/skills.js b/api/server/routes/skills.js index 2143e50f60..dd40662750 100644 --- a/api/server/routes/skills.js +++ b/api/server/routes/skills.js @@ -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 diff --git a/api/server/services/Skills/handlers.js b/api/server/services/Skills/handlers.js new file mode 100644 index 0000000000..f224cac34e --- /dev/null +++ b/api/server/services/Skills/handlers.js @@ -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 }; diff --git a/docs/skills-management-api.md b/docs/skills-management-api.md new file mode 100644 index 0000000000..27329a59d0 --- /dev/null +++ b/docs/skills-management-api.md @@ -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. diff --git a/packages/api/src/agents/management.ts b/packages/api/src/agents/management.ts index 51694e2dec..af834b0609 100644 --- a/packages/api/src/agents/management.ts +++ b/packages/api/src/agents/management.ts @@ -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 'not_found', 'permission_denied', 'internal_error', + 'conflict', ]); const agentManagementValidationIssueSchema = z @@ -308,6 +310,7 @@ const ERROR_STATUS: Record = { not_found: 404, permission_denied: 403, internal_error: 500, + conflict: 409, }; const ERROR_MESSAGE: Record = { @@ -315,6 +318,7 @@ const ERROR_MESSAGE: Record = { 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. */ diff --git a/packages/api/src/skills/handlers.ts b/packages/api/src/skills/handlers.ts index 3d8472a55e..3a9fefc903 100644 --- a/packages/api/src/skills/handlers.ts +++ b/packages/api/src/skills/handlers.ts @@ -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; 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; + listSkillsByAccess: (params: ListSkillsByAccessParams) => Promise; updateSkill: (params: { id: string; expectedVersion: number; @@ -303,6 +299,10 @@ function blockFilteredSkillContent( return false; } +type SkillResponseOptions = { includePublicStatus?: boolean }; + +type SkillListOptions = Pick; + /** * 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; + list: (req: ServerRequest, res: Response, options?: SkillListOptions) => Promise; create: (req: ServerRequest, res: Response) => Promise; - get: (req: ServerRequest, res: Response) => Promise; - patch: (req: ServerRequest, res: Response) => Promise; + get: (req: ServerRequest, res: Response, options?: SkillResponseOptions) => Promise; + patch: (req: ServerRequest, res: Response, options?: SkillResponseOptions) => Promise; delete: (req: ServerRequest, res: Response) => Promise; listFiles: (req: ServerRequest, res: Response) => Promise; downloadFile: (req: ServerRequest, res: Response) => Promise; @@ -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' }); } diff --git a/packages/api/src/skills/index.ts b/packages/api/src/skills/index.ts index fd363b1c97..706126377b 100644 --- a/packages/api/src/skills/index.ts +++ b/packages/api/src/skills/index.ts @@ -8,3 +8,4 @@ export * from './parse'; export * from './skillStates'; export * from './deployment'; export * from './sync'; +export * from './management'; diff --git a/packages/api/src/skills/management.spec.ts b/packages/api/src/skills/management.spec.ts new file mode 100644 index 0000000000..685647122a --- /dev/null +++ b/packages/api/src/skills/management.spec.ts @@ -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; +let filters: FiltersConfig | undefined; +let readSkill: jest.SpyInstance; +let beforeList: jest.Mock; +let uploadLimiter: jest.MockedFunction; +let accessible: jest.Mock; +let publiclyAccessible: jest.Mock; +let publicStatus: jest.Mock; +let capabilityCheck: jest.Mock; +let originalStrict: string | undefined; +const inTenant = (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((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); +}); diff --git a/packages/api/src/skills/management.ts b/packages/api/src/skills/management.ts new file mode 100644 index 0000000000..d33fec3506 --- /dev/null +++ b/packages/api/src/skills/management.ts @@ -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 = 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 = 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 = + 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 & { + resourceAccess?: { + resourceInfo: NonNullable>>; + }; + }; + +type SkillHandler = (req: ServerRequest, res: Response) => Promise; +type Projector = (body: unknown) => object; +export interface SkillManagementDeps { + handlers: SkillsHandlers; + beforeList?: (req: ServerRequest) => Promise; + 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[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((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 +> { + async function canManageSkills(req: ManagementRequest): Promise { + 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, + ) { + return async (request: Request, res: Response): Promise => { + 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 }); + }), + }; +} diff --git a/packages/data-schemas/src/methods/skill.ts b/packages/data-schemas/src/methods/skill.ts index 8d03bc16c0..8c600f0892 100644 --- a/packages/data-schemas/src/methods/skill.ts +++ b/packages/data-schemas/src/methods/skill.ts @@ -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, + params: Pick< + ListSkillsByAccessParams, + 'accessibleIds' | 'category' | 'search' | 'manageTenantId' + >, ): FilterQuery { - const filter: FilterQuery = { - _id: { $in: params.accessibleIds }, - }; + const filter: FilterQuery = params.manageTenantId + ? { tenantId: params.manageTenantId } + : { _id: { $in: params.accessibleIds } }; if (params.category && params.category.length > 0) { filter.category = params.category; }