Skip to content

Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active

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

Dustin Healya03d90e1dcaf
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({
@@ -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<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.
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<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',
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<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);
+ });
+});
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<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);
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<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 },
+ ),
};
}
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<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
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<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));
+}
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<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 };
}