🧩 feat: Add Skill Creation and File Deletion to Management API (#16878)

* feat: complete Skill management CRUD

* fix: make Skill file deletion retryable

* fix: delete local Skill files by recorded owner

* fix: narrow skill management CRUD and honor blob owners

* fix: preserve request-scoped storage deletion ownership
This commit is contained in:
Dustin Healy 2026-10-16 09:05:03 -07:00 • committed by GitHub
parent 60a8b3dec0
commit a03d90e1dc
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
22 changed files with 1236 additions and 303 deletions

View file

@ -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`)

View file

@ -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' } } }),

View file

@ -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';

View file

@ -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);
});

View file

@ -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

View file

@ -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.

View file

@ -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);
});
});

View file

@ -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<void>}
* 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=<timestamp>) */
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.

View file

@ -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.

View file

@ -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": {

View file

@ -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<string, ZodTypeAny> = {
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',

View file

@ -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<void>((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);
});
});

View file

@ -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 = {

View file

@ -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<SkillManagementDeps['saveFile']>;
@ -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);

View file

@ -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<SkillFrontmatterValue> = z.l
);
export type SkillManagementUpdate = TUpdateSkillPayload & { expectedVersion: number };
export const skillManagementCreateSchema: z.ZodType<TCreateSkill> = 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<SkillManagementUpdate> = 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<TDeleteSkillFileResponse> = 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<Response>
> {
async function canManageSkills(req: ManagementRequest): Promise<boolean> {
@ -225,17 +248,18 @@ export function createSkillManagementHandlers(
function wrap(
permission: PermissionBits | undefined,
operation: (req: ManagementRequest, res: Response) => Promise<Response>,
options: { mutation?: boolean } = {},
) {
return async (request: Request, res: Response): Promise<Response> => {
const req = request as ManagementRequest;
try {
if (!req.user?.id || !req.user.tenantId) return sendError(res, 'permission_denied');
const editing = permission === PermissionBits.EDIT;
const 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 },
),
};
}

View file

@ -7,3 +7,4 @@ export * from './metadata';
export * from './url';
export * from './path';
export * from './local';
export * from './ownedBlobDelete';

View file

@ -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);
});
});

View file

@ -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<unknown>;
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<void> => {
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

View file

@ -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) });
});
});

View file

@ -0,0 +1,61 @@
interface StoredBlobFile {
filepath: string;
user?: { toString(): string };
}
interface OwnedBlobDeleteDependencies {
extractPath: (url: string) => string;
deleteBlob: (path: string) => Promise<unknown>;
isMissing: (error: unknown) => boolean;
deleteRagFile: (args: { userId: string; file: StoredBlobFile }) => Promise<unknown>;
}
/** 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<void> => {
const ownerId = req.user.id;
const blobPath = extractPath(file.filepath);
const segments = blobPath.split('/');
// saveBuffer stores at <basePath>/<ownerId>/<filename>; 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));
}

View file

@ -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(

View file

@ -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<ISkillFileDocument>;
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 };
}