diff --git a/api/server/routes/agents/__tests__/openapi.contract.spec.js b/api/server/routes/agents/__tests__/openapi.contract.spec.js index 6a97570165..7c44bae8d1 100644 --- a/api/server/routes/agents/__tests__/openapi.contract.spec.js +++ b/api/server/routes/agents/__tests__/openapi.contract.spec.js @@ -108,6 +108,7 @@ describe('Agents OpenAPI actual HTTP contract', () => { await mongoose.connect(mongoServer.getUri()); createModels(mongoose); db = require('~/models'); + await db.seedDefaultRoles(); user = await mongoose.models.User.create({ email: 'openapi-contract@example.test', @@ -240,8 +241,9 @@ describe('Agents OpenAPI actual HTTP contract', () => { }); const { getSkillManagementFileSaver } = require('~/server/services/Endpoints/agents/skillDeps'); + const { getSkillsHandlers } = require('~/server/services/Skills/handlers'); const skillHandlers = createSkillManagementHandlers({ - handlers: {}, + handlers: getSkillsHandlers(), getSkillById: db.getSkillById, getRoleByName, checkPermission: async () => true, @@ -263,7 +265,9 @@ describe('Agents OpenAPI actual HTTP contract', () => { restoreTenantContextFromReq, fileHandlers.upload, ); + app.post('/api/agents/v1/skills', skillHandlers.create); app.put('/api/agents/v1/skills/:id/files/*relativePath', skillHandlers.updateFile); + app.delete('/api/agents/v1/skills/:id/files/*relativePath', skillHandlers.deleteFile); app.get('/api/agents/v1/agents/:id', (_req, _res, next) => next(new Error('contract fixture escaped error')), ); @@ -353,6 +357,40 @@ describe('Agents OpenAPI actual HTTP contract', () => { expect(fs.readFileSync(diskPath, 'utf8')).toBe(content); }); + it('documents and validates Skill creation and file deletion', async () => { + const created = await request(app) + .post('/api/agents/v1/skills') + .set('Authorization', `Bearer ${token}`) + .send({ + name: 'managed-contract-skill', + description: 'Created through the versioned management contract.', + body: '# Managed contract Skill', + }); + expect(created.status).toBe(201); + expectResponseToMatchSpec(spec, 'createSkill', created); + expect(await mongoose.models.Skill.findById(created.body.id).lean()).toMatchObject({ + tenantId, + }); + + const file = await request(app) + .put(`/api/agents/v1/skills/${created.body.id}/files/references/delete-me.md`) + .set('Authorization', `Bearer ${token}`) + .send({ content: 'temporary' }); + expect(file.status).toBe(200); + + const deletedFile = await request(app) + .delete(`/api/agents/v1/skills/${created.body.id}/files/references/delete-me.md`) + .set('Authorization', `Bearer ${token}`); + expect(deletedFile.status).toBe(200); + expectResponseToMatchSpec(spec, 'deleteSkillFile', deletedFile); + expect( + await mongoose.models.SkillFile.findOne({ + skillId: created.body.id, + relativePath: 'references/delete-me.md', + }).lean(), + ).toBeNull(); + }); + it('validates parser and normalized management errors against their documented JSON forms', async () => { const malformed = await request(app) .put(`/api/agents/v1/skills/${skillId}/files/contract.md`) diff --git a/api/server/routes/agents/__tests__/skills.spec.js b/api/server/routes/agents/__tests__/skills.spec.js index b7f3b04528..a17750443a 100644 --- a/api/server/routes/agents/__tests__/skills.spec.js +++ b/api/server/routes/agents/__tests__/skills.spec.js @@ -14,11 +14,13 @@ jest.mock('@librechat/api', () => ({ mockDeps = deps; return { list: mockList, + create: mockWrite, get: mockList, update: mockWrite, listFiles: mockList, getFile: mockList, updateFile: mockWrite, + deleteFile: mockWrite, }; }, mapAgentManagementError: () => ({ status: 404, body: { error: { code: 'not_found' } } }), diff --git a/api/server/routes/agents/skills.js b/api/server/routes/agents/skills.js index 0d83148034..509f11b2b1 100644 --- a/api/server/routes/agents/skills.js +++ b/api/server/routes/agents/skills.js @@ -27,11 +27,13 @@ const handlers = createSkillManagementHandlers({ }); router.use(requireAgentManagementAuth, requireTermsAcceptance, checkBan, configMiddleware); router.get('/', handlers.list); +router.post('/', handlers.create); 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.delete('/:id/files/*relativePath', handlers.deleteFile); router.use((_req, res) => { const { status, body } = mapAgentManagementError('not_found'); body.error.message = 'Skill or file not found'; diff --git a/api/server/routes/skills.test.js b/api/server/routes/skills.test.js index 92272ae899..545c98dafe 100644 --- a/api/server/routes/skills.test.js +++ b/api/server/routes/skills.test.js @@ -58,6 +58,7 @@ jest.mock('~/server/middleware/config/app', () => (req, _res, next) => { jest.mock('~/server/services/Files/strategies', () => ({ getStrategyFunctions: jest.fn().mockReturnValue({ saveBuffer: jest.fn().mockResolvedValue('/uploads/test/file.txt'), + deleteFile: jest.fn().mockResolvedValue(undefined), getDownloadStream: jest.fn().mockResolvedValue({ pipe: jest.fn(), on: jest.fn(), @@ -871,7 +872,7 @@ describe('Skill routes', () => { expect((await upload('stale', initial.body.file_id)).status).toBe(409); const stored = await SkillFile.findOne({ skillId: created.body._id }); expect(stored.file_id).toBe(replaced.body.file_id); - await request(app).delete(`${url}/references/revision.md`); + await request(app).delete(`${url}/references/revision.md`).expect(200); expect((await upload('resurrect', replaced.body.file_id)).status).toBe(409); expect(await SkillFile.countDocuments({ skillId: created.body._id })).toBe(0); }); diff --git a/api/server/services/Files/Azure/crud.js b/api/server/services/Files/Azure/crud.js index 1fea4db7d5..ee2cb8e40d 100644 --- a/api/server/services/Files/Azure/crud.js +++ b/api/server/services/Files/Azure/crud.js @@ -5,6 +5,8 @@ const fetch = require('node-fetch'); const { logger } = require('@librechat/data-schemas'); const { deleteRagFile, + createOwnedBlobFileDeleter, + extractAzureBlobPath, assertRemoteFileURL, getSafeErrorMetadata, getAzureContainerClient, @@ -120,26 +122,18 @@ async function getAzureURL({ fileName, basePath = defaultBasePath, userId, conta * @param {ServerRequest} params.req - The Express request object. * @param {MongoFile} params.file - The file object. */ -async function deleteFileFromAzure(req, file) { - await deleteRagFile({ userId: req.user.id, file }); - - try { - const containerClient = await getAzureContainerClient(AZURE_CONTAINER_NAME); - const blobPath = file.filepath.split(`${AZURE_CONTAINER_NAME}/`)[1]; - if (!blobPath.includes(req.user.id)) { - throw new Error('User ID not found in blob path'); - } - const blockBlobClient = containerClient.getBlockBlobClient(blobPath); - await blockBlobClient.delete(); - logger.debug('[deleteFileFromAzure] Blob deleted successfully from Azure Blob Storage'); - } catch (error) { - logger.error('[deleteFileFromAzure] Error deleting blob:', error); - if (error.statusCode === 404) { - return; - } - throw error; - } -} +const deleteFileFromAzure = (req, file) => + createOwnedBlobFileDeleter({ + extractPath: (filepath) => extractAzureBlobPath(filepath, AZURE_CONTAINER_NAME), + deleteBlob: async (blobPath) => { + const containerClient = await getAzureContainerClient(AZURE_CONTAINER_NAME); + const blockBlobClient = containerClient.getBlockBlobClient(blobPath); + await blockBlobClient.delete(); + logger.debug('[deleteFileFromAzure] Blob deleted successfully from Azure Blob Storage'); + }, + isMissing: (error) => error?.statusCode === 404, + deleteRagFile, + })(req, file); /** * Streams a file from disk directly to Azure Blob Storage without loading diff --git a/api/server/services/Files/Firebase/crud.js b/api/server/services/Files/Firebase/crud.js index 174b473751..997f871f88 100644 --- a/api/server/services/Files/Firebase/crud.js +++ b/api/server/services/Files/Firebase/crud.js @@ -5,6 +5,8 @@ const fetch = require('node-fetch'); const { logger } = require('@librechat/data-schemas'); const { deleteRagFile, + createOwnedBlobFileDeleter, + extractFirebaseBlobPath, getFirebaseStorage, assertRemoteFileURL, getSafeErrorMetadata, @@ -153,26 +155,6 @@ async function saveBufferToFirebase({ userId, buffer, fileName, basePath = 'imag * @param {string} urlString - The Firebase Storage URL. * @returns {string} The decoded file path. */ -function extractFirebaseFilePath(urlString) { - try { - const url = new URL(urlString); - const pathRegex = /\/o\/(.+?)(\?|$)/; - const match = url.pathname.match(pathRegex); - - if (match && match[1]) { - return decodeURIComponent(match[1]); - } - - return ''; - } catch { - logger.debug( - '[extractFirebaseFilePath] Failed to extract Firebase file path from URL, returning empty string', - ); - // If URL parsing fails, return an empty string - return ''; - } -} - /** * Deletes a file from Firebase storage. This function determines the filepath from the * Firebase storage URL via regex for deletion. Validated by the user's ID. @@ -185,23 +167,13 @@ function extractFirebaseFilePath(urlString) { * A promise that resolves when the file has been successfully deleted from Firebase storage. * Throws an error if there is an issue with deletion. */ -const deleteFirebaseFile = async (req, file) => { - await deleteRagFile({ userId: req.user.id, file }); - - const fileName = extractFirebaseFilePath(file.filepath); - if (!fileName.includes(req.user.id)) { - throw new Error('Invalid file path'); - } - try { - await deleteFile('', fileName); - } catch (error) { - logger.error('Error deleting file from Firebase:', error); - if (error.code === 'storage/object-not-found') { - return; - } - throw error; - } -}; +const deleteFirebaseFile = (req, file) => + createOwnedBlobFileDeleter({ + extractPath: extractFirebaseBlobPath, + deleteBlob: (filepath) => deleteFile('', filepath), + isMissing: (error) => error?.code === 'storage/object-not-found', + deleteRagFile, + })(req, file); /** * Uploads a file to Firebase Storage. diff --git a/api/server/services/Files/Local/__tests__/crud-delete.spec.js b/api/server/services/Files/Local/__tests__/crud-delete.spec.js deleted file mode 100644 index 7a7a30340a..0000000000 --- a/api/server/services/Files/Local/__tests__/crud-delete.spec.js +++ /dev/null @@ -1,70 +0,0 @@ -/** Exactly what `deleteLocalFile` reaches for, so the double does not depend on a built package. */ -jest.mock('@librechat/api', () => ({ - deleteRagFile: jest.fn().mockResolvedValue(undefined), - stripCacheBust: (filepath) => String(filepath).split('?')[0], -})); -jest.mock('@librechat/data-schemas', () => ({ - logger: { warn: jest.fn(), error: jest.fn() }, -})); - -const fs = require('fs'); -const os = require('os'); -const path = require('path'); -const { deleteLocalFile } = require('../crud'); - -/* The resolved promise of a delete is what `processDeleteRequest` reads to decide that a record may - lose its metadata and its agent references, so this adapter may only resolve once the bytes are - actually gone. Storage that was already missing is the one benign case. */ -describe('deleteLocalFile failure reporting', () => { - const userId = 'user-1'; - let tmpBase; - let req; - - beforeEach(() => { - jest.restoreAllMocks(); - tmpBase = fs.mkdtempSync(path.join(os.tmpdir(), 'crud-delete-')); - fs.mkdirSync(path.join(tmpBase, 'uploads', userId), { recursive: true }); - req = { - user: { id: userId }, - config: { - paths: { - publicPath: path.join(tmpBase, 'public'), - uploads: path.join(tmpBase, 'uploads'), - }, - }, - }; - }); - - afterEach(() => { - fs.rmSync(tmpBase, { recursive: true, force: true }); - }); - - const uploadedFile = (filename) => { - const filepath = path.join(tmpBase, 'uploads', userId, filename); - fs.writeFileSync(filepath, 'contents'); - return { file_id: 'file-1', filepath: `/uploads/${userId}/${filename}` }; - }; - - it('removes the file and resolves', async () => { - const file = uploadedFile('knowledge.txt'); - - await expect(deleteLocalFile(req, file)).resolves.toBeUndefined(); - expect(fs.existsSync(path.join(tmpBase, 'uploads', userId, 'knowledge.txt'))).toBe(false); - }); - - it('resolves when the file is already gone', async () => { - await expect( - deleteLocalFile(req, { file_id: 'file-1', filepath: `/uploads/${userId}/missing.txt` }), - ).resolves.toBeUndefined(); - }); - - it('rejects when the bytes survive the delete', async () => { - const file = uploadedFile('locked.txt'); - jest - .spyOn(fs.promises, 'unlink') - .mockRejectedValue(Object.assign(new Error('permission denied'), { code: 'EACCES' })); - - await expect(deleteLocalFile(req, file)).rejects.toThrow('permission denied'); - expect(fs.existsSync(path.join(tmpBase, 'uploads', userId, 'locked.txt'))).toBe(true); - }); -}); diff --git a/api/server/services/Files/Local/crud.js b/api/server/services/Files/Local/crud.js index 12a28ba889..3ec4e7569b 100644 --- a/api/server/services/Files/Local/crud.js +++ b/api/server/services/Files/Local/crud.js @@ -3,6 +3,7 @@ const path = require('path'); const axios = require('axios'); const { deleteRagFile, + createLocalFileDeleter, stripCacheBust, writeLocalFile, assertRemoteFileURL, @@ -12,7 +13,6 @@ const { saveLocalBuffer: saveBufferToLocalPath, } = require('@librechat/api'); const { logger } = require('@librechat/data-schemas'); -const { EModelEndpoint } = require('librechat-data-provider'); const { resizeImageBuffer } = require('~/server/services/Files/images/resize'); const { getBufferMetadata } = require('~/server/utils'); const paths = require('~/config/paths'); @@ -114,100 +114,7 @@ async function getLocalFileURL({ fileName, basePath = 'images' }) { return path.posix.join('/', basePath, fileName); } -/** - * Validates that a filepath is strictly contained within a subdirectory under a base path, - * using path.relative to prevent prefix-collision bypasses. - * - * @param {ServerRequest} req - The request object from Express. It should contain a `user` property with an `id`. - * @param {string} base - The base directory path. - * @param {string} subfolder - The subdirectory under the base path. - * @param {string} filepath - The complete file path to be validated. - * - * @returns {boolean} - * Returns true if the filepath is within the specified base and subfolder, false otherwise. - */ -const isValidPath = (req, base, subfolder, filepath) => { - const normalizedBase = path.resolve(base, subfolder, req.user.id); - const normalizedFilepath = path.resolve(filepath); - const rel = path.relative(normalizedBase, normalizedFilepath); - return !rel.startsWith('..') && !path.isAbsolute(rel) && !rel.includes(`..${path.sep}`); -}; - -/** - * @param {string} filepath - */ -/** - * A file whose bytes are still on disk must not be reported as deleted: callers use the resolved - * promise to decide that a record may lose its metadata and its agent references. Storage that was - * already gone is the one benign case, and `processDeleteRequest` treats it as deleted by design. - */ -const unlinkFile = async (filepath) => { - try { - await fs.promises.unlink(filepath); - } catch (error) { - if (error?.code === 'ENOENT') { - logger.warn('Local file was already missing during delete:', error); - return; - } - logger.error('Error deleting file:', error); - throw error; - } -}; - -/** - * Deletes a file from the filesystem. This function takes a file object, constructs the full path, and - * verifies the path's validity before deleting the file. If the path is invalid, an error is thrown. - * - * @param {ServerRequest} req - The request object from Express. - * @param {MongoFile} file - The file object to be deleted. It should have a `filepath` property that is - * a string representing the path of the file relative to the publicPath. - * - * @returns {Promise} - * A promise that resolves when the file has been successfully deleted, or throws an error if the - * file path is invalid or if there is an error in deletion. - */ -const deleteLocalFile = async (req, file) => { - const appConfig = req.config; - const { publicPath, uploads } = appConfig.paths; - - /** Filepath stripped of query parameters (e.g., ?manual=true, ?v=) */ - const cleanFilepath = stripCacheBust(file.filepath); - - await deleteRagFile({ userId: req.user.id, file }); - - if (cleanFilepath.startsWith(`/uploads/${req.user.id}`)) { - const userUploadDir = path.join(uploads, req.user.id); - const basePath = cleanFilepath.split(`/uploads/${req.user.id}/`)[1]; - - if (!basePath) { - throw new Error(`Invalid file path: ${cleanFilepath}`); - } - - const filepath = path.join(userUploadDir, basePath); - - const rel = path.relative(userUploadDir, filepath); - if (rel.startsWith('..') || path.isAbsolute(rel) || rel.includes(`..${path.sep}`)) { - throw new Error(`Invalid file path: ${cleanFilepath}`); - } - - await unlinkFile(filepath); - return; - } - - const parts = cleanFilepath.split(path.sep); - const subfolder = parts[1]; - if (!subfolder && parts[0] === EModelEndpoint.agents) { - logger.warn(`Agent File ${file.file_id} is missing filepath, may have been deleted already`); - return; - } - const filepath = path.join(publicPath, cleanFilepath); - - if (!isValidPath(req, publicPath, subfolder, filepath)) { - throw new Error('Invalid file path'); - } - - await unlinkFile(filepath); -}; +const deleteLocalFile = (req, file) => createLocalFileDeleter({ deleteRagFile, logger })(req, file); /** * Uploads a file to the specified upload directory. diff --git a/docs/skills-management-api.md b/docs/skills-management-api.md index 27329a59d0..6bd5944301 100644 --- a/docs/skills-management-api.md +++ b/docs/skills-management-api.md @@ -7,17 +7,32 @@ execution router and does not accept browser sessions or execution API keys as f | Method | Path | Operation | | ------ | ----------------------------------------------- | --------------------------------------------- | | GET | `/api/agents/v1/skills` | List accessible Skills (`limit` and `cursor`) | +| POST | `/api/agents/v1/skills` | Create an inline Skill | | 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 | +| DELETE | `/api/agents/v1/skills/:id/files/*relativePath` | Delete a 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. +Create an inline Skill with its required identity and instruction fields: + +```json +{ + "name": "query-review", + "description": "Review a query and recommend improvements.", + "body": "Review the supplied query for correctness and efficiency." +} +``` + +Creation also accepts the editable optional fields described below. The authenticated principal is +recorded as the owner; callers cannot set ownership, tenant, source, or permissions. + Updates require the version returned by the latest read: ```json @@ -36,11 +51,12 @@ 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. +rejected. Delete the same path to remove the file. 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. File deletion completes +storage cleanup before returning success and reports a conflict if another writer replaced the path. 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/openapi/agents.openapi.json b/packages/api/openapi/agents.openapi.json index fb2b0e08e5..b54c81e888 100644 --- a/packages/api/openapi/agents.openapi.json +++ b/packages/api/openapi/agents.openapi.json @@ -1249,6 +1249,140 @@ } } } + }, + "post": { + "operationId": "createSkill", + "summary": "Create a skill", + "tags": [ + "Skills" + ], + "security": [ + { + "oidcBearer": [] + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SkillCreateRequest" + } + } + } + }, + "responses": { + "201": { + "description": "The created skill", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Skill" + } + } + } + }, + "400": { + "description": "Invalid request, or a malformed JSON body", + "content": { + "application/json": { + "schema": { + "anyOf": [ + { + "$ref": "#/components/schemas/Error" + }, + { + "$ref": "#/components/schemas/JsonParseError" + } + ] + } + } + } + }, + "401": { + "description": "Authentication failed", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorMessage" + } + } + } + }, + "403": { + "description": "Permission denied, the caller is banned, or the request fails tenant isolation", + "content": { + "application/json": { + "schema": { + "anyOf": [ + { + "$ref": "#/components/schemas/Error" + }, + { + "$ref": "#/components/schemas/MessageError" + }, + { + "$ref": "#/components/schemas/ErrorMessage" + } + ] + } + } + } + }, + "404": { + "description": "Not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "409": { + "description": "The Skill name already exists, or the bound account is being deleted", + "content": { + "application/json": { + "schema": { + "anyOf": [ + { + "$ref": "#/components/schemas/Error" + }, + { + "$ref": "#/components/schemas/AccountDeletionConflict" + } + ] + } + } + } + }, + "500": { + "description": "Internal server error. Errors normalized by the route use JSON; the final application error controller sends a text body with the text/html media type.", + "content": { + "application/json": { + "schema": { + "anyOf": [ + { + "$ref": "#/components/schemas/Error" + }, + { + "$ref": "#/components/schemas/ErrorMessage" + } + ] + } + }, + "text/html": { + "schema": { + "type": "string", + "enum": [ + "An unknown error occurred.", + "Processing error in ErrorController." + ] + } + } + } + } + } } }, "/skills/{id}": { @@ -1794,6 +1928,150 @@ } } }, + "delete": { + "operationId": "deleteSkillFile", + "summary": "Delete a skill's file", + "tags": [ + "Skills" + ], + "security": [ + { + "oidcBearer": [] + } + ], + "parameters": [ + { + "in": "path", + "name": "id", + "description": "The skill id", + "schema": { + "type": "string" + }, + "required": true + }, + { + "in": "path", + "name": "relativePath", + "description": "The file path within the skill", + "schema": { + "type": "string" + }, + "required": true + } + ], + "responses": { + "200": { + "description": "The file was deleted", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SkillFileDeleted" + } + } + } + }, + "400": { + "description": "Invalid request, or a malformed JSON body", + "content": { + "application/json": { + "schema": { + "anyOf": [ + { + "$ref": "#/components/schemas/Error" + }, + { + "$ref": "#/components/schemas/JsonParseError" + } + ] + } + } + } + }, + "401": { + "description": "Authentication failed", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorMessage" + } + } + } + }, + "403": { + "description": "Permission denied, the caller is banned, or the request fails tenant isolation", + "content": { + "application/json": { + "schema": { + "anyOf": [ + { + "$ref": "#/components/schemas/Error" + }, + { + "$ref": "#/components/schemas/MessageError" + }, + { + "$ref": "#/components/schemas/ErrorMessage" + } + ] + } + } + } + }, + "404": { + "description": "Not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "409": { + "description": "The file changed while it was being deleted, or the bound account is being deleted", + "content": { + "application/json": { + "schema": { + "anyOf": [ + { + "$ref": "#/components/schemas/Error" + }, + { + "$ref": "#/components/schemas/AccountDeletionConflict" + } + ] + } + } + } + }, + "500": { + "description": "Internal server error. Errors normalized by the route use JSON; the final application error controller sends a text body with the text/html media type.", + "content": { + "application/json": { + "schema": { + "anyOf": [ + { + "$ref": "#/components/schemas/Error" + }, + { + "$ref": "#/components/schemas/ErrorMessage" + } + ] + } + }, + "text/html": { + "schema": { + "type": "string", + "enum": [ + "An unknown error occurred.", + "Processing error in ErrorController." + ] + } + } + } + } + } + }, "put": { "operationId": "updateSkillFile", "summary": "Create or update a skill's file", @@ -3807,6 +4085,41 @@ "after" ] }, + "SkillCreateRequest": { + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "displayTitle": { + "type": "string" + }, + "description": { + "type": "string" + }, + "body": { + "type": "string" + }, + "frontmatter": { + "type": "object", + "additionalProperties": { + "$ref": "#/components/schemas/SkillFrontmatterValue" + } + }, + "category": { + "type": "string" + }, + "alwaysApply": { + "type": "boolean" + } + }, + "required": [ + "name", + "description", + "body" + ], + "additionalProperties": false + }, "SkillUpdateRequest": { "type": "object", "properties": { @@ -3949,6 +4262,27 @@ "bytes" ] }, + "SkillFileDeleted": { + "type": "object", + "properties": { + "skillId": { + "type": "string", + "pattern": "^[a-f\\d]{24}$" + }, + "relativePath": { + "type": "string" + }, + "deleted": { + "type": "boolean", + "const": true + } + }, + "required": [ + "skillId", + "relativePath", + "deleted" + ] + }, "ErrorMessage": { "type": "object", "properties": { diff --git a/packages/api/src/openapi/skills.ts b/packages/api/src/openapi/skills.ts index 023aed223a..6fa595fb68 100644 --- a/packages/api/src/openapi/skills.ts +++ b/packages/api/src/openapi/skills.ts @@ -3,12 +3,14 @@ import type { ZodTypeAny } from 'zod'; import type { EndpointContract } from './adapter'; import { skillManagementUpdateSchema, + skillManagementCreateSchema, skillManagementResponseSchema, skillSummarySchema, skillFileSchema, skillFileContentSchema, skillFileUpdateSchema, skillFrontmatterValueSchema, + skillFileDeleteResponseSchema, } from '../skills/management'; import { errorMessageResponseSchema, @@ -42,12 +44,14 @@ export const skillComponentSchemas: Record = { SkillFrontmatterValue: skillFrontmatterValueSchema, Skill: skillManagementResponseSchema, SkillList: skillListResponseSchema, + SkillCreateRequest: skillManagementCreateSchema, SkillUpdateRequest: skillManagementUpdateSchema, SkillFile: skillFileSchema, SkillFileList: skillFileListResponseSchema, SkillFileContent: skillFileContentSchema, SkillFileUpdateRequest: skillFileUpdateSchema, SkillFileUpdated: skillFileUpdatedSchema, + SkillFileDeleted: skillFileDeleteResponseSchema, }; const errorResponses = [ @@ -95,6 +99,24 @@ export const skillContracts: EndpointContract[] = [ ...errorResponses, ], }, + { + operationId: 'createSkill', + method: 'post', + path: '/skills', + tags: [TAG], + summary: 'Create a skill', + security: SECURITY, + body: skillManagementCreateSchema, + responses: [ + { status: 201, description: 'The created skill', schema: skillManagementResponseSchema }, + ...errorResponses, + { + status: 409, + description: 'The Skill name already exists, or the bound account is being deleted', + schema: z.union([agentManagementErrorSchema, accountDeletionResponseSchema]), + }, + ], + }, { operationId: 'getSkill', method: 'get', @@ -157,6 +179,28 @@ export const skillContracts: EndpointContract[] = [ ...errorResponses, ], }, + { + operationId: 'deleteSkillFile', + method: 'delete', + path: '/skills/{id}/files/{relativePath}', + tags: [TAG], + summary: "Delete a skill's file", + security: SECURITY, + pathParams: [ + { name: 'id', description: 'The skill id' }, + { name: 'relativePath', description: 'The file path within the skill' }, + ], + responses: [ + { status: 200, description: 'The file was deleted', schema: skillFileDeleteResponseSchema }, + ...errorResponses, + { + status: 409, + description: + 'The file changed while it was being deleted, or the bound account is being deleted', + schema: z.union([agentManagementErrorSchema, accountDeletionResponseSchema]), + }, + ], + }, { operationId: 'updateSkillFile', method: 'put', diff --git a/packages/api/src/skills/handlers.spec.ts b/packages/api/src/skills/handlers.spec.ts index ab991206fd..54ed7a2816 100644 --- a/packages/api/src/skills/handlers.spec.ts +++ b/packages/api/src/skills/handlers.spec.ts @@ -1,8 +1,17 @@ +import os from 'os'; +import path from 'path'; import { Types } from 'mongoose'; +import { promises as fs } from 'fs'; import type { DeleteSkillResult, ISkillFile } from '@librechat/data-schemas'; import type { Response } from 'express'; import type { SkillsHandlersDeps } from './handlers'; import type { ServerRequest } from '~/types'; +import { + createOwnedBlobFileDeleter, + extractAzureBlobPath, + extractFirebaseBlobPath, +} from '~/storage/ownedBlobDelete'; +import { createLocalFileDeleter } from '~/storage/local'; import { createSkillsHandlers } from './handlers'; function mockResponse(): Response { @@ -33,6 +42,7 @@ describe('skill delete handler', () => { relativePath: 'references/query.sql', filepath: '/uploads/query.sql', source: 'local', + author: new Types.ObjectId(), } as ISkillFile & { _id: Types.ObjectId }; const handlers = createSkillsHandlers({ deleteSkill, @@ -40,7 +50,7 @@ describe('skill delete handler', () => { getStrategyFunctions: jest.fn(() => ({ deleteFile: deleteBlob })), isValidObjectIdString: jest.fn(() => true), } as unknown as SkillsHandlersDeps); - const req = { params: { id } } as unknown as ServerRequest; + const req = { params: { id }, user: { id: 'manager-1' } } as unknown as ServerRequest; const res = mockResponse(); await handlers.delete(req, res); @@ -93,12 +103,13 @@ describe('skill delete handler', () => { relativePath: 'references/query.sql', filepath: '/uploads/query.sql', source: 'local', + author: new Types.ObjectId(), } as ISkillFile & { _id: Types.ObjectId }, ]), getStrategyFunctions: jest.fn(() => ({ deleteFile: deleteBlob })), isValidObjectIdString: jest.fn(() => true), } as unknown as SkillsHandlersDeps); - const req = { params: { id } } as unknown as ServerRequest; + const req = { params: { id }, user: { id: 'manager-1' } } as unknown as ServerRequest; const res = mockResponse(); await handlers.delete(req, res); @@ -109,6 +120,147 @@ describe('skill delete handler', () => { }); }); +describe.each([ + { + source: 'azure_blob', + filepath: 'https://example.blob.core.windows.net/files/uploads/author-1/file.txt', + extractPath: (url: string) => extractAzureBlobPath(url, 'files'), + }, + { + source: 'firebase', + filepath: 'https://firebasestorage.googleapis.com/v0/b/bucket/o/uploads%2Fauthor-1%2Ffile.txt', + extractPath: extractFirebaseBlobPath, + }, +])( + 'cross-author Skill file deletion through $source storage', + ({ source, filepath, extractPath }) => { + it('deletes with the persisted author while the manager remains the requester', async () => { + const skillId = new Types.ObjectId().toString(); + const file = { + file_id: 'file-1', + filepath, + source, + author: new Types.ObjectId(), + relativePath: 'references/file.txt', + } as ISkillFile & { _id: Types.ObjectId }; + const ownerId = file.author.toString(); + const ownedFilepath = filepath.replace('author-1', ownerId); + file.filepath = ownedFilepath; + const deleteBlob = jest.fn().mockResolvedValue(undefined); + const deleteRagFile = jest.fn().mockResolvedValue(undefined); + const storageDelete = createOwnedBlobFileDeleter({ + extractPath, + deleteBlob, + deleteRagFile, + isMissing: () => false, + }); + const deleteSkillFile = jest.fn().mockResolvedValue({ deleted: true }); + const storageDeleteSpy = jest.fn(storageDelete); + const handlers = createSkillsHandlers({ + getSkillFileByPath: jest.fn().mockResolvedValue(file), + getStrategyFunctions: jest.fn(() => ({ deleteFile: storageDeleteSpy })), + deleteSkillFile, + } as unknown as SkillsHandlersDeps); + const req = { + params: { id: skillId, relativePath: 'references/file.txt' }, + user: { id: 'manager-1', tenantId: 'tenant-1' }, + } as unknown as ServerRequest; + const res = mockResponse(); + + await handlers.deleteFile(req, res); + + expect(deleteBlob).toHaveBeenCalledWith(`uploads/${ownerId}/file.txt`); + expect(deleteRagFile).toHaveBeenCalledWith({ + userId: ownerId, + file: expect.objectContaining({ user: ownerId }), + }); + expect(deleteSkillFile).toHaveBeenCalledWith(skillId, 'references/file.txt', 'file-1'); + expect(res.status).toHaveBeenCalledWith(200); + expect(storageDeleteSpy.mock.calls[0][0]).toMatchObject({ + user: { id: ownerId, tenantId: 'tenant-1' }, + }); + expect(req.user).toEqual({ id: 'manager-1', tenantId: 'tenant-1' }); + }); + }, +); + +describe('Skill file storage ownership', () => { + it('deletes a loaded cross-author Local file without changing the authenticated request', async () => { + const root = await fs.mkdtemp(path.join(os.tmpdir(), 'skill-owner-')); + try { + const author = new Types.ObjectId(); + const ownerId = author.toString(); + const uploads = path.join(root, 'uploads'); + const diskPath = path.join(uploads, ownerId, 'file.txt'); + await fs.mkdir(path.dirname(diskPath), { recursive: true }); + await fs.writeFile(diskPath, 'contents'); + const file = { + file_id: 'file-1', + filepath: `/uploads/${ownerId}/file.txt`, + source: 'local', + author, + } as ISkillFile & { _id: Types.ObjectId }; + const deleteRagFile = jest.fn().mockResolvedValue(undefined); + const storageDelete = createLocalFileDeleter({ + deleteRagFile, + logger: { warn: jest.fn(), error: jest.fn() }, + }); + const handlers = createSkillsHandlers({ + getSkillFileByPath: jest.fn().mockResolvedValue(file), + getStrategyFunctions: () => ({ deleteFile: storageDelete }), + deleteSkillFile: jest.fn().mockResolvedValue({ deleted: true }), + } as unknown as SkillsHandlersDeps); + const req = { + params: { id: new Types.ObjectId().toString(), relativePath: 'file.txt' }, + user: { id: 'manager-1', tenantId: 'tenant-1' }, + config: { paths: { uploads, publicPath: path.join(root, 'public') } }, + } as unknown as ServerRequest; + const res = mockResponse(); + + await handlers.deleteFile(req, res); + + await expect(fs.access(diskPath)).rejects.toMatchObject({ code: 'ENOENT' }); + expect(deleteRagFile).toHaveBeenCalledWith({ + userId: ownerId, + file: expect.objectContaining({ user: ownerId }), + }); + expect(req.user).toEqual({ id: 'manager-1', tenantId: 'tenant-1' }); + expect(res.status).toHaveBeenCalledWith(200); + } finally { + await fs.rm(root, { recursive: true, force: true }); + } + }); + + it.each([undefined, ''])( + 'does not fall back to the manager for a missing author (%s)', + async (author) => { + const deleteBlob = jest.fn(); + const deleteSkillFile = jest.fn(); + const handlers = createSkillsHandlers({ + getSkillFileByPath: jest.fn().mockResolvedValue({ + file_id: 'file-1', + filepath: '/uploads/manager-1/file.txt', + source: 'local', + author, + }), + getStrategyFunctions: () => ({ deleteFile: deleteBlob }), + deleteSkillFile, + } as unknown as SkillsHandlersDeps); + const req = { + params: { id: new Types.ObjectId().toString(), relativePath: 'file.txt' }, + user: { id: 'manager-1' }, + } as unknown as ServerRequest; + const res = mockResponse(); + + await handlers.deleteFile(req, res); + + expect(deleteBlob).not.toHaveBeenCalled(); + expect(deleteSkillFile).not.toHaveBeenCalled(); + expect(res.status).toHaveBeenCalledWith(500); + }, + ); +}); + describe('skill create handler', () => { it('retries dependent cleanup after owner permission setup fails', async () => { const skillId = new Types.ObjectId(); @@ -148,3 +300,78 @@ describe('skill create handler', () => { expect(res.status).toHaveBeenCalledWith(500); }); }); + +describe('skill file delete handler', () => { + const id = new Types.ObjectId().toString(); + const file = { + _id: new Types.ObjectId(), + file_id: 'file-revision', + relativePath: 'references/guide.md', + filepath: '/uploads/guide.md', + source: 'local', + author: new Types.ObjectId(), + tenantId: 'tenant-1', + } as ISkillFile & { _id: Types.ObjectId }; + const req = { + params: { id, relativePath: 'references/guide.md' }, + user: { id: 'manager-1', tenantId: 'tenant-1' }, + } as unknown as ServerRequest; + + it('waits for blob cleanup before conditionally deleting the file record', async () => { + let releaseBlob!: () => void; + const deleteBlob = jest.fn( + () => + new Promise((resolve) => { + releaseBlob = resolve; + }), + ); + const deleteSkillFile = jest.fn(async () => ({ deleted: true })); + const handlers = createSkillsHandlers({ + getSkillFileByPath: jest.fn(async () => file), + deleteSkillFile, + getStrategyFunctions: jest.fn(() => ({ deleteFile: deleteBlob })), + } as unknown as SkillsHandlersDeps); + const res = mockResponse(); + + const pending = handlers.deleteFile(req, res); + await Promise.resolve(); + expect(deleteSkillFile).not.toHaveBeenCalled(); + releaseBlob(); + await pending; + + expect(deleteSkillFile).toHaveBeenCalledWith(id, 'references/guide.md', 'file-revision'); + expect(res.status).toHaveBeenCalledWith(200); + }); + + it('keeps the file record retryable when blob cleanup fails', async () => { + const deleteSkillFile = jest.fn(); + const handlers = createSkillsHandlers({ + getSkillFileByPath: jest.fn(async () => file), + deleteSkillFile, + getStrategyFunctions: jest.fn(() => ({ + deleteFile: jest.fn(async () => { + throw new Error('storage unavailable'); + }), + })), + } as unknown as SkillsHandlersDeps); + const res = mockResponse(); + + await handlers.deleteFile(req, res); + + expect(deleteSkillFile).not.toHaveBeenCalled(); + expect(res.status).toHaveBeenCalledWith(500); + }); + + it('reports a conflict when a concurrent writer replaces the path', async () => { + const handlers = createSkillsHandlers({ + getSkillFileByPath: jest.fn(async () => file), + deleteSkillFile: jest.fn(async () => ({ deleted: false })), + getStrategyFunctions: jest.fn(() => ({ deleteFile: jest.fn(async () => undefined) })), + } as unknown as SkillsHandlersDeps); + const res = mockResponse(); + + await handlers.deleteFile(req, res); + + expect(res.status).toHaveBeenCalledWith(409); + }); +}); diff --git a/packages/api/src/skills/handlers.ts b/packages/api/src/skills/handlers.ts index c22d384c55..d8e727b730 100644 --- a/packages/api/src/skills/handlers.ts +++ b/packages/api/src/skills/handlers.ts @@ -49,6 +49,13 @@ type SkillValidationError = Error & { code?: string; issues?: ValidationIssue[] /** Mongo duplicate-key shape. */ type DuplicateKeyError = Error & { code?: number | string }; +/** Only authorized, loaded SkillFile records may select another storage owner. */ +function skillFileDeletionRequest(req: ServerRequest, file: ISkillFile): ServerRequest { + const ownerId = file.author?.toString(); + if (!ownerId || !req.user) throw new Error('Skill file has no storage owner'); + return { ...req, user: { ...req.user, id: ownerId, _id: file.author } } as ServerRequest; +} + /** * All dependencies required to serve skill HTTP requests. Every dep is resolved * from the legacy api layer (`~/models`, `PermissionService`) so the TS handlers @@ -71,6 +78,7 @@ export interface SkillsHandlersDeps { deleteSkillFile: ( skillId: string | Types.ObjectId, relativePath: string, + expectedFileId?: string, ) => Promise<{ deleted: boolean }>; /** Access-control primitives from PermissionService. */ @@ -622,7 +630,7 @@ export function createSkillsHandlers(deps: SkillsHandlersDeps): { if (!deleteBlob) { throw new Error(`No delete strategy for ${file.source}`); } - await deleteBlob(req, { + await deleteBlob(skillFileDeletionRequest(req, file), { filepath: file.filepath, storageKey: file.storageKey, storageRegion: file.storageRegion, @@ -852,21 +860,22 @@ export function createSkillsHandlers(deps: SkillsHandlersDeps): { return res.status(404).json({ error: 'Skill file not found' }); } - const result = await deleteSkillFile(id, decodedPath); - if (!result.deleted) { - return res.status(404).json({ error: 'Skill file not found' }); - } - - // Clean up the stored blob — fire-and-forget so the response isn't delayed const { deleteFile: deleteBlob } = getStrategyFunctions(file.source); - if (deleteBlob) { - deleteBlob(req, { - filepath: file.filepath, - storageKey: file.storageKey, - storageRegion: file.storageRegion, - user: file.author?.toString?.(), - tenantId: file.tenantId?.toString?.(), - }).catch((e) => logger.error('[deleteFile] Storage cleanup failed:', e)); + if (!deleteBlob) { + logger.error(`[deleteFile] No delete strategy for ${file.source}`); + return res.status(500).json({ error: 'Error deleting skill file' }); + } + await deleteBlob(skillFileDeletionRequest(req, file), { + filepath: file.filepath, + storageKey: file.storageKey, + storageRegion: file.storageRegion, + user: file.author?.toString?.(), + tenantId: file.tenantId?.toString?.(), + }); + + const result = await deleteSkillFile(id, decodedPath, file.file_id); + if (!result.deleted) { + return res.status(409).json({ error: 'Skill file changed while it was being deleted' }); } const response: TDeleteSkillFileResponse = { diff --git a/packages/api/src/skills/management.spec.ts b/packages/api/src/skills/management.spec.ts index 18478404a4..de4faddab7 100644 --- a/packages/api/src/skills/management.spec.ts +++ b/packages/api/src/skills/management.spec.ts @@ -23,6 +23,7 @@ let skillId: string; let allowEdit: boolean; let allowView: boolean; let allowUse: boolean; +let allowCreate: boolean; let canManage: boolean; let authenticated: boolean; let saveFile: jest.MockedFunction; @@ -56,6 +57,7 @@ beforeEach(async () => { allowEdit = true; allowView = true; allowUse = true; + allowCreate = true; canManage = false; authenticated = true; filters = undefined; @@ -87,7 +89,7 @@ beforeEach(async () => { findPubliclyAccessibleResources: publiclyAccessible, hasPublicPermission: publicStatus, grantPermission: async () => undefined, - getStrategyFunctions: () => ({}), + getStrategyFunctions: () => ({ deleteFile: async () => undefined }), isValidObjectIdString: (id) => typeof id === 'string' && /^[a-f\d]{24}$/i.test(id), }); const management = createSkillManagementHandlers({ @@ -100,12 +102,14 @@ beforeEach(async () => { permissions: { [PermissionTypes.SKILLS]: { [Permissions.USE]: allowUse, - [Permissions.CREATE]: true, + [Permissions.CREATE]: allowCreate, }, }, }) as IRole, - checkPermission: async ({ requiredPermission }) => - requiredPermission === PermissionBits.EDIT ? allowEdit : allowView, + checkPermission: async ({ requiredPermission }) => { + if (requiredPermission === PermissionBits.EDIT) return allowEdit; + return allowView; + }, saveFile, hasCapability: capabilityCheck, }); @@ -119,6 +123,9 @@ beforeEach(async () => { app.get('/skills', async (req, res) => { await management.list(req, res); }); + app.post('/skills', async (req, res) => { + await management.create(req, res); + }); app.get('/skills/:id', async (req, res) => { await management.get(req, res); }); @@ -134,6 +141,52 @@ beforeEach(async () => { app.put('/skills/:id/files/*relativePath', async (req, res) => { await management.updateFile(req, res); }); + app.delete('/skills/:id/files/*relativePath', async (req, res) => { + await management.deleteFile(req, res); + }); +}); + +it('creates an inline tenant Skill and returns the versioned representation', async () => { + const response = await request(app) + .post('/skills') + .send({ + name: 'created-skill', + description: 'A newly created management Skill.', + body: 'Created instructions', + }) + .expect(201); + expect(response.body).toMatchObject({ + name: 'created-skill', + body: 'Created instructions', + version: 1, + }); + expect(response.body.id).toMatch(/^[a-f\d]{24}$/i); + expect(response.body).not.toHaveProperty('_id'); + expect(await inTenant(() => db.getSkillById(response.body.id))).toMatchObject({ + tenantId, + source: 'inline', + }); +}); + +it.each([ + { name: 'missing-body', description: 'Missing body.' }, + { name: 'forged-tenant', description: 'Forged tenant.', body: 'x', tenantId: 'foreign' }, + { name: 'forged-author', description: 'Forged author.', body: 'x', author: 'caller' }, + { name: 'forged-source', description: 'Forged source.', body: 'x', source: 'github' }, +])('rejects malformed or caller-controlled creation input %j', async (body) => { + await request(app).post('/skills').send(body).expect(400); +}); + +it('requires create capability for management mutations', async () => { + allowCreate = false; + await request(app) + .post('/skills') + .send({ name: 'denied', description: 'Denied Skill.', body: 'Denied' }) + .expect(403); + await request(app) + .patch(`/skills/${skillId}`) + .send({ expectedVersion: 1, body: 'Denied' }) + .expect(403); }); it('lists and retrieves stable representations without ownership or storage internals', async () => { @@ -210,6 +263,7 @@ it('hides inaccessible and cross-tenant Skills, including on file writes', async .put(`/skills/${skillId}/files/reference.md`) .send({ content: 'x' }) .expect(404); + await request(app).delete(`/skills/${skillId}/files/reference.md`).expect(404); expect(saveFile).not.toHaveBeenCalled(); allowView = true; allowEdit = true; @@ -257,6 +311,7 @@ it('keeps synchronized Skill content and files read-only', async () => { .put(`/skills/${skillId}/files/reference.md`) .send({ content: 'x' }) .expect(403); + await request(app).delete(`/skills/${skillId}/files/reference.md`).expect(403); expect(saveFile).not.toHaveBeenCalled(); }); it('writes nested text files through existing storage and rejects unsafe paths', async () => { @@ -284,6 +339,32 @@ it('writes nested text files through existing storage and rejects unsafe paths', } expect(saveFile).not.toHaveBeenCalled(); }); +it('deletes nested Skill files and rejects unsafe paths', async () => { + await inTenant(() => + db.upsertSkillFile({ + skillId, + relativePath: 'references/guide.md', + file_id: 'file-revision', + filename: 'guide.md', + filepath: '/uploads/guide.md', + source: 'local', + mimeType: 'text/markdown', + bytes: 5, + author, + tenantId, + }), + ); + const response = await request(app) + .delete(`/skills/${skillId}/files/references/guide.md`) + .expect(200); + expect(response.body).toEqual({ + skillId, + relativePath: 'references/guide.md', + deleted: true, + }); + expect(await inTenant(() => db.getSkillFileByPath(skillId, 'references/guide.md'))).toBeNull(); + await request(app).delete(`/skills/${skillId}/files/..%2Fescape.md`).expect(400); +}); 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); diff --git a/packages/api/src/skills/management.ts b/packages/api/src/skills/management.ts index b209f92d44..9d0d9bec96 100644 --- a/packages/api/src/skills/management.ts +++ b/packages/api/src/skills/management.ts @@ -6,7 +6,13 @@ import { PermissionTypes, ResourceType, } from 'librechat-data-provider'; -import type { SkillFrontmatterValue, TSkill, TUpdateSkillPayload } from 'librechat-data-provider'; +import type { + SkillFrontmatterValue, + TCreateSkill, + TDeleteSkillFileResponse, + 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'; @@ -38,6 +44,18 @@ export const skillFrontmatterValueSchema: z.ZodType = z.l ); export type SkillManagementUpdate = TUpdateSkillPayload & { expectedVersion: number }; +export const skillManagementCreateSchema: z.ZodType = z + .object({ + name: fields.name, + displayTitle: fields.displayTitle, + description: fields.description, + body: z.string(), + frontmatter: z.record(skillFrontmatterValueSchema).optional(), + category: fields.category, + alwaysApply: fields.alwaysApply, + }) + .strict(); + export const skillManagementUpdateSchema: z.ZodType = z .object({ name: fields.name.optional(), @@ -107,6 +125,11 @@ export const skillFileContentSchema: z.AnyZodObject = skillFileSchema.extend({ export const skillFileUpdateSchema: z.AnyZodObject = z .object({ content: z.string().max(1024 * 1024) }) .strict(); +export const skillFileDeleteResponseSchema: z.ZodType = z.object({ + skillId: idSchema, + relativePath: z.string(), + deleted: z.literal(true), +}); const listSchema = agentManagementListSchema; type ManagementRequest = Request & @@ -210,7 +233,7 @@ async function admitFileWrite(req: Request, res: Response, limiters: RequestHand export function createSkillManagementHandlers( deps: SkillManagementDeps, ): Record< - 'list' | 'get' | 'update' | 'listFiles' | 'getFile' | 'updateFile', + 'list' | 'create' | 'get' | 'update' | 'listFiles' | 'getFile' | 'updateFile' | 'deleteFile', (request: Request, res: Response) => Promise > { async function canManageSkills(req: ManagementRequest): Promise { @@ -225,17 +248,18 @@ export function createSkillManagementHandlers( function wrap( permission: PermissionBits | undefined, operation: (req: ManagementRequest, res: Response) => Promise, + options: { mutation?: boolean } = {}, ) { 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 mutation = options.mutation === true; const allowed = await checkAccessWithRequestCache({ req, user: req.user, permissionType: PermissionTypes.SKILLS, - permissions: editing ? [Permissions.USE, Permissions.CREATE] : [Permissions.USE], + permissions: mutation ? [Permissions.USE, Permissions.CREATE] : [Permissions.USE], getRoleByName: deps.getRoleByName, }); if (!allowed) return sendError(res, 'permission_denied'); @@ -260,7 +284,7 @@ export function createSkillManagementHandlers( })) ) return sendError(res, 'not_found'); - if (editing && (deployment || skill.source !== 'inline')) + if (mutation && (deployment || skill.source !== 'inline')) return sendError(res, 'permission_denied'); req.resourceAccess = { resourceInfo: skill }; } @@ -310,6 +334,16 @@ export function createSkillManagementHandlers( }, ); }), + create: wrap( + undefined, + async (req, res) => { + const parsed = skillManagementCreateSchema.safeParse(req.body); + if (!parsed.success) return sendError(res, 'invalid_request', parsed.error); + req.body = parsed.data; + return runHandler(req, res, deps.handlers.create, (body) => projectSkill(body, true)); + }, + { mutation: true }, + ), get: wrap(PermissionBits.VIEW, (req, res) => runHandler( req, @@ -318,18 +352,22 @@ export function createSkillManagementHandlers( (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), - ); - }), + 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), + ); + }, + { mutation: true }, + ), listFiles: wrap(PermissionBits.VIEW, (req, res) => runHandler(req, res, deps.handlers.listFiles, (body) => ({ object: 'list', @@ -342,41 +380,58 @@ export function createSkillManagementHandlers( skillFileContentSchema.parse(body), ); }), - updateFile: wrap(PermissionBits.EDIT, async (req, res) => { - const parsed = skillFileUpdateSchema.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; - try { - 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 }); - } catch (error) { - if (error instanceof Error && 'code' in error && error.code === 'SKILL_FILE_CONFLICT') { - return sendError(res, 'conflict'); + updateFile: wrap( + PermissionBits.EDIT, + async (req, res) => { + const parsed = skillFileUpdateSchema.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'); } - throw error; - } - }), + if (!(await admitFileWrite(req, res, deps.fileWriteLimiters ?? []))) return res; + try { + 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 }); + } catch (error) { + if (error instanceof Error && 'code' in error && error.code === 'SKILL_FILE_CONFLICT') { + return sendError(res, 'conflict'); + } + throw error; + } + }, + { mutation: true }, + ), + deleteFile: wrap( + PermissionBits.EDIT, + async (req, res) => { + const relativePath = resolveSkillFilePathParam(req.params.relativePath); + if (relativePath == null || validateRelativePath(relativePath).length > 0) + return sendError(res, 'invalid_request'); + req.params.relativePath = relativePath; + return runHandler(req, res, deps.handlers.deleteFile, (body) => + skillFileDeleteResponseSchema.parse(body), + ); + }, + { mutation: true }, + ), }; } diff --git a/packages/api/src/storage/index.ts b/packages/api/src/storage/index.ts index 3639c5fa65..d6e6922efb 100644 --- a/packages/api/src/storage/index.ts +++ b/packages/api/src/storage/index.ts @@ -7,3 +7,4 @@ export * from './metadata'; export * from './url'; export * from './path'; export * from './local'; +export * from './ownedBlobDelete'; diff --git a/packages/api/src/storage/local-delete.spec.ts b/packages/api/src/storage/local-delete.spec.ts new file mode 100644 index 0000000000..22c8c883ac --- /dev/null +++ b/packages/api/src/storage/local-delete.spec.ts @@ -0,0 +1,81 @@ +import fs from 'fs'; +import os from 'os'; +import path from 'path'; +import { createLocalFileDeleter } from './local'; + +describe('local file deletion', () => { + let root: string; + let req: { user: { id: string }; config: { paths: { publicPath: string; uploads: string } } }; + const deleteRagFile = jest.fn().mockResolvedValue(undefined); + const logger = { warn: jest.fn(), error: jest.fn() }; + const remove = createLocalFileDeleter({ deleteRagFile, logger }); + + beforeEach(() => { + jest.clearAllMocks(); + root = fs.mkdtempSync(path.join(os.tmpdir(), 'local-delete-')); + req = { + user: { id: 'user-1' }, + config: { + paths: { publicPath: path.join(root, 'public'), uploads: path.join(root, 'uploads') }, + }, + }; + }); + + afterEach(() => fs.rmSync(root, { recursive: true, force: true })); + + const uploadedFile = (name: string, owner = 'user-1') => { + const dir = path.join(root, 'uploads', owner); + fs.mkdirSync(dir, { recursive: true }); + fs.writeFileSync(path.join(dir, name), 'contents'); + return { file_id: 'file-1', filepath: `/uploads/${owner}/${name}`, user: owner }; + }; + + it('removes uploaded bytes and RAG data', async () => { + const file = uploadedFile('knowledge.txt'); + await remove(req, file); + expect(fs.existsSync(path.join(root, 'uploads', 'user-1', 'knowledge.txt'))).toBe(false); + expect(deleteRagFile).toHaveBeenCalledWith({ userId: 'user-1', file }); + }); + + it('accepts missing storage but rejects other unlink failures', async () => { + const file = { file_id: 'file-1', filepath: '/uploads/user-1/missing.txt', user: 'user-1' }; + await expect(remove(req, file)).resolves.toBeUndefined(); + + const directory = path.join(root, 'uploads', 'user-1', 'not-a-file'); + fs.mkdirSync(directory, { recursive: true }); + const existing = { file_id: 'file-2', filepath: '/uploads/user-1/not-a-file', user: 'user-1' }; + await expect(remove(req, existing)).rejects.toThrow(); + expect(fs.existsSync(directory)).toBe(true); + }); + + it('keeps deletion scoped to the request owner, not descriptor metadata', async () => { + const file = uploadedFile('managed.txt', 'user-2'); + await expect(remove(req, file)).rejects.toThrow('Invalid file path'); + expect(deleteRagFile).not.toHaveBeenCalled(); + expect(fs.existsSync(path.join(root, 'uploads', 'user-2', 'managed.txt'))).toBe(true); + + req.user.id = 'user-2'; + await remove(req, file); + expect(deleteRagFile).toHaveBeenCalledWith({ userId: 'user-2', file }); + + const other = uploadedFile('protected.txt', 'user-2'); + req.user.id = 'user-3'; + deleteRagFile.mockClear(); + await expect(remove(req, other)).rejects.toThrow('Invalid file path'); + expect(deleteRagFile).not.toHaveBeenCalled(); + }); + + it('cleans up RAG data for a legacy agent record without a disk path', async () => { + const file = { file_id: 'file-1', filepath: 'agents', user: 'user-2' }; + await remove(req, file); + expect(deleteRagFile).toHaveBeenCalledWith({ userId: 'user-1', file }); + }); + + it('rejects an empty request owner before touching storage or RAG data', async () => { + const file = uploadedFile('retained.txt'); + req.user.id = ''; + await expect(remove(req, file)).rejects.toThrow('Invalid file owner'); + expect(deleteRagFile).not.toHaveBeenCalled(); + expect(fs.existsSync(path.join(root, 'uploads', 'user-1', 'retained.txt'))).toBe(true); + }); +}); diff --git a/packages/api/src/storage/local.ts b/packages/api/src/storage/local.ts index 5b9de9acb3..829b013d14 100644 --- a/packages/api/src/storage/local.ts +++ b/packages/api/src/storage/local.ts @@ -1,12 +1,84 @@ import path from 'path'; import crypto from 'node:crypto'; +import { EModelEndpoint } from 'librechat-data-provider'; import { mkdir, copyFile, rename, unlink, writeFile } from 'fs/promises'; +import { stripCacheBust } from './path'; export interface LocalStoragePaths { publicPath: string; uploads: string; } +interface LocalFile { + file_id: string; + filepath: string; + user?: { toString(): string }; +} + +interface LocalDeleteRequest { + user: { id: string }; + config: { paths: LocalStoragePaths }; +} + +interface LocalFileDeleteDependencies { + deleteRagFile: (args: { userId: string; file: LocalFile }) => Promise; + logger: { warn: (...args: unknown[]) => void; error: (...args: unknown[]) => void }; +} + +/** Deletes only within the request owner's namespace, and reports storage failures to callers. */ +export function createLocalFileDeleter({ deleteRagFile, logger }: LocalFileDeleteDependencies) { + const unlinkStoredFile = async (filepath: string) => { + try { + await unlink(filepath); + } catch (error) { + if ((error as NodeJS.ErrnoException).code === 'ENOENT') { + logger.warn('Local file was already missing during delete:', error); + return; + } + logger.error('Error deleting file:', error); + throw error; + } + }; + + return async (req: LocalDeleteRequest, file: LocalFile): Promise => { + const { publicPath, uploads } = req.config.paths; + const ownerId = req.user.id; + if (!ownerId) throw new Error('Invalid file owner'); + const cleanFilepath = stripCacheBust(file.filepath); + const uploadPrefix = `/uploads/${ownerId}/`; + + if (cleanFilepath.startsWith(uploadPrefix)) { + const userUploadDir = path.join(uploads, ownerId); + const filePath = path.join(userUploadDir, cleanFilepath.slice(uploadPrefix.length)); + if (!isStrictlyWithin(userUploadDir, filePath)) { + throw new Error(`Invalid file path: ${cleanFilepath}`); + } + await deleteRagFile({ userId: ownerId, file }); + await unlinkStoredFile(filePath); + return; + } + + const parts = cleanFilepath.split(path.sep); + const subfolder = parts[1]; + if (!subfolder && parts[0] === EModelEndpoint.agents) { + await deleteRagFile({ userId: ownerId, file }); + logger.warn(`Agent File ${file.file_id} is missing filepath, may have been deleted already`); + return; + } + const filePath = path.join(publicPath, cleanFilepath); + if (!subfolder || !isStrictlyWithin(path.join(publicPath, subfolder, ownerId), filePath)) { + throw new Error('Invalid file path'); + } + await deleteRagFile({ userId: ownerId, file }); + await unlinkStoredFile(filePath); + }; +} + +function isStrictlyWithin(directory: string, filePath: string): boolean { + const rel = path.relative(path.resolve(directory), path.resolve(filePath)); + return !!rel && !rel.startsWith('..') && !path.isAbsolute(rel) && !rel.includes(`..${path.sep}`); +} + /** * Fills a sibling temp file and renames it into place, so concurrent writers to one path each * land whole (last rename wins) and readers never see a partly written file. The temp name is diff --git a/packages/api/src/storage/ownedBlobDelete.spec.ts b/packages/api/src/storage/ownedBlobDelete.spec.ts new file mode 100644 index 0000000000..d0e2610f70 --- /dev/null +++ b/packages/api/src/storage/ownedBlobDelete.spec.ts @@ -0,0 +1,77 @@ +import { + createOwnedBlobFileDeleter, + extractAzureBlobPath, + extractFirebaseBlobPath, +} from './ownedBlobDelete'; + +describe.each([ + { + source: 'Azure', + filepath: 'https://example.blob.core.windows.net/files/uploads/author-1/file.txt', + extractPath: (url: string) => extractAzureBlobPath(url, 'files'), + }, + { + source: 'Firebase', + filepath: 'https://firebasestorage.googleapis.com/v0/b/bucket/o/uploads%2Fauthor-1%2Ffile.txt', + extractPath: extractFirebaseBlobPath, + }, +])('$source owner-aware deletion', ({ filepath, extractPath }) => { + const deleteBlob = jest.fn().mockResolvedValue(undefined); + const deleteRagFile = jest.fn().mockResolvedValue(undefined); + const remove = createOwnedBlobFileDeleter({ + extractPath, + deleteBlob, + deleteRagFile, + isMissing: (error) => (error as { code?: string }).code === 'missing', + }); + const req = { user: { id: 'author-1' } }; + + beforeEach(() => { + deleteBlob.mockReset().mockResolvedValue(undefined); + deleteRagFile.mockClear(); + }); + + it('deletes a file under the request owner', async () => { + const file = { filepath, user: 'author-1' }; + await remove(req, file); + expect(deleteBlob).toHaveBeenCalledWith('uploads/author-1/file.txt'); + expect(deleteRagFile).toHaveBeenCalledWith({ userId: 'author-1', file }); + }); + + it('rejects an owner mismatch before deleting either blob or RAG data', async () => { + await expect( + remove({ user: { id: 'author-2' } }, { filepath, user: 'author-1' }), + ).rejects.toThrow('Invalid file path'); + expect(deleteBlob).not.toHaveBeenCalled(); + expect(deleteRagFile).not.toHaveBeenCalled(); + }); + + it('does not let descriptor ownership change the request owner', async () => { + const file = { filepath, user: 'descriptor-owner' }; + await remove(req, file); + expect(deleteBlob).toHaveBeenCalledWith('uploads/author-1/file.txt'); + expect(deleteRagFile).toHaveBeenCalledWith({ userId: 'author-1', file }); + }); + + it('rejects an empty request owner without invoking either provider', async () => { + await expect(remove({ user: { id: '' } }, { filepath, user: 'author-1' })).rejects.toThrow( + 'Invalid file path', + ); + expect(deleteBlob).not.toHaveBeenCalled(); + expect(deleteRagFile).not.toHaveBeenCalled(); + }); + + it('does not clean up RAG data when remote deletion fails', async () => { + deleteBlob.mockRejectedValueOnce(new Error('storage unavailable')); + await expect(remove(req, { filepath, user: 'author-1' })).rejects.toThrow( + 'storage unavailable', + ); + expect(deleteRagFile).not.toHaveBeenCalled(); + }); + + it('treats an already missing blob as deleted and still cleans up RAG data', async () => { + deleteBlob.mockRejectedValueOnce(Object.assign(new Error('gone'), { code: 'missing' })); + await remove(req, { filepath, user: 'author-1' }); + expect(deleteRagFile).toHaveBeenCalledWith({ userId: 'author-1', file: expect.any(Object) }); + }); +}); diff --git a/packages/api/src/storage/ownedBlobDelete.ts b/packages/api/src/storage/ownedBlobDelete.ts new file mode 100644 index 0000000000..d8ed747864 --- /dev/null +++ b/packages/api/src/storage/ownedBlobDelete.ts @@ -0,0 +1,61 @@ +interface StoredBlobFile { + filepath: string; + user?: { toString(): string }; +} + +interface OwnedBlobDeleteDependencies { + extractPath: (url: string) => string; + deleteBlob: (path: string) => Promise; + isMissing: (error: unknown) => boolean; + deleteRagFile: (args: { userId: string; file: StoredBlobFile }) => Promise; +} + +/** File descriptors cannot override the storage owner supplied by the request. */ +export function createOwnedBlobFileDeleter({ + extractPath, + deleteBlob, + isMissing, + deleteRagFile, +}: OwnedBlobDeleteDependencies) { + return async (req: { user: { id: string } }, file: StoredBlobFile): Promise => { + const ownerId = req.user.id; + const blobPath = extractPath(file.filepath); + const segments = blobPath.split('/'); + // saveBuffer stores at //; the exact owner segment + // must be adjacent to the file name, not merely a substring elsewhere in the URL. + if ( + !ownerId || + segments.length < 3 || + segments[segments.length - 2] !== ownerId || + !segments[segments.length - 1] + ) { + throw new Error('Invalid file path'); + } + + try { + await deleteBlob(blobPath); + } catch (error) { + if (!isMissing(error)) throw error; + } + await deleteRagFile({ userId: ownerId, file }); + }; +} + +export function extractAzureBlobPath(filepath: string, containerName: string): string { + const segments = new URL(filepath).pathname.split('/').filter(Boolean); + const containerIndex = segments.indexOf(containerName); + if (containerIndex < 0 || containerIndex === segments.length - 1) { + throw new Error('Invalid Azure blob path'); + } + return segments + .slice(containerIndex + 1) + .map(decodeURIComponent) + .join('/'); +} + +export function extractFirebaseBlobPath(filepath: string): string { + const pathname = new URL(filepath).pathname; + const objectIndex = pathname.indexOf('/o/'); + if (objectIndex < 0) throw new Error('Invalid Firebase blob path'); + return decodeURIComponent(pathname.slice(objectIndex + 3)); +} diff --git a/packages/data-schemas/src/methods/skill.spec.ts b/packages/data-schemas/src/methods/skill.spec.ts index a326c7cad9..ee752a3fa1 100644 --- a/packages/data-schemas/src/methods/skill.spec.ts +++ b/packages/data-schemas/src/methods/skill.spec.ts @@ -2198,6 +2198,29 @@ describe('SkillFile methods', () => { expect(after?.version).toBe(4); }); + it('deleteSkillFile preserves a concurrently replaced file when its revision changed', async () => { + const { skill } = await methods.createSkill(makeSkillInput()); + await methods.upsertSkillFile({ + skillId: skill._id, + relativePath: 'references/guide.md', + file_id: 'current-revision', + filename: 'guide.md', + filepath: '/guide', + source: 'local', + mimeType: 'text/markdown', + bytes: 1, + author: owner._id, + }); + + await expect( + methods.deleteSkillFile(skill._id, 'references/guide.md', 'stale-revision'), + ).resolves.toEqual({ deleted: false }); + expect(await methods.getSkillFileByPath(skill._id, 'references/guide.md')).toMatchObject({ + file_id: 'current-revision', + }); + expect(await methods.getSkillById(skill._id)).toMatchObject({ fileCount: 1, version: 2 }); + }); + it('rejects invalid paths via upsertSkillFile', async () => { const { skill } = await methods.createSkill(makeSkillInput()); await expect( diff --git a/packages/data-schemas/src/methods/skill.ts b/packages/data-schemas/src/methods/skill.ts index 9a94db9a56..8c25dda640 100644 --- a/packages/data-schemas/src/methods/skill.ts +++ b/packages/data-schemas/src/methods/skill.ts @@ -1066,6 +1066,7 @@ export function createSkillMethods( deleteSkillFile: ( skillId: Types.ObjectId | string, relativePath: string, + expectedFileId?: string, ) => Promise<{ deleted: boolean }>; getSkillFileByPath: ( skillId: Types.ObjectId | string, @@ -1920,9 +1921,14 @@ export function createSkillMethods( async function deleteSkillFile( skillId: Types.ObjectId | string, relativePath: string, + expectedFileId?: string, ): Promise<{ deleted: boolean }> { const SkillFile = mongoose.models.SkillFile as Model; - const res = await SkillFile.deleteOne({ skillId, relativePath }); + const res = await SkillFile.deleteOne({ + skillId, + relativePath, + ...(expectedFileId != null ? { file_id: expectedFileId } : {}), + }); if (!res.deletedCount) { return { deleted: false }; }