¶ FileCage API — File Storage Service
?? Rebrand (2026-08-26): Este proyecto fue renombrado de FileVault a FileCage. Nuevo dominio: filecage.com
? PROYECTO COMPLETADO — 2026-08-26
- API: https://filecage.com
- Landing: https://filecage.com (neon cyberpunk dark — v2.5.0)
- CLI: FileCage CLI v2.5.0 con VIRO mascota ASCII
- Repo API: https://gitxub.neosolutions.com.ar/Cloe/FileCage
- Repo Landing: https://gitxub.neosolutions.com.ar/Cloe/filecage-landing
API REST minimalista para crear carpetas protegidas con contraseña, y subir/bajar/listar/borrar archivos.
¶ 
Checklist de Implementacion
¶ 1. Setup inicial ?
- Crear repo en Gitea interno ? https://gitxub.neosolutions.com.ar/Cloe/FileCage
-
npm init— inicializar proyecto Node.js - Instalar dependencias:
express,multer,bcryptjs,swagger-jsdoc,swagger-ui-express - Crear estructura de carpetas del proyecto
¶ 2. Desarrollo — Utils y Middleware ?
-
src/utils/uid.js— generador de UID de 8 chars (charset A-Z sin O + 0-9) -
src/middleware/auth.js— validarX-Passwordcontra bcrypt del.meta.jsonde la carpeta
¶ 3. Desarrollo — Endpoints ?
-
POST /folders— crear carpeta + generar UID + guardar password hasheada en.meta.json -
POST /folders/:uid/files— subir archivo (multer, limite 100MB, validar duplicados ? 409) -
GET /folders/:uid/files— listar archivos de la carpeta con nombre, tamaño y fecha -
GET /folders/:uid/files/:filename— descargar archivo como stream -
DELETE /folders/:uid/files/:filename— borrar archivo
¶ 4. Manejo de errores ?
-
401— password incorrecta o header ausente -
404— carpeta o archivo no encontrado -
409— archivo ya existe con ese nombre -
413— archivo supera 100 MB
¶ 5. Swagger ?
-
src/swagger.js— configuracion de swagger-jsdoc - Agregar anotaciones JSDoc en cada endpoint
- Verificar que
/api-docsfuncione correctamente
¶ 6. Docker ?
- Escribir
Dockerfile(sin docker-compose) -
.dockerignoreconfigurado - Endpoint
/healthagregado (usado por HEALTHCHECK) - Build de imagen en Contabo ?
- Test con volumen montado —
/data/filevaultverificado en host ?
¶ 7. Repo y versionado ?
- Commits por etapa en Gitea ? https://gitxub.neosolutions.com.ar/Cloe/FileCage
-
.gitignore(node_modules, storage/, logs/) - Push a Gitea
¶ 8. Deploy en Contabo ?
- Crear directorio
/data/filevaulten Contabo - Clonar repo desde Gitea
- Build de imagen
filevault:latest - Container corriendo en puerto
3301(3300 ocupado por vault-front) - Volumen montado:
-v /data/filevault:/app/storagedocker run -d \ --name filevault \ --restart unless-stopped \ -p 127.0.0.1:3300:3300 \ -v /data/filevault:/app/storage \ filevault:latest
¶ 9. Nginx + SSL ?
- Config nginx
filecage.com?127.0.0.1:3301 -
proxy_set_header X-Password $http_x_password— cabecera custom forwardeada -
client_max_body_size 105M— para uploads de hasta 100MB - Timeouts: read/send 120s para archivos grandes
- SSL Let's Encrypt via certbot ? (expira 2026-11-24)
- Redirect HTTP ? HTTPS
¶ 10. Verificacion final ?
- Crear carpeta via API y recibir UID
- Subir archivo de prueba
- Listar archivos de la carpeta
- Descargar el archivo subido
- Borrar el archivo
- Password incorrecta ?
401 - Archivo >100MB ?
413 - Swagger en
https://filecage.com/api-docs - Persistencia verificada: archivos visibles en
/data/filevault/del host ?
¶ 
Nota de Desarrollo — WSL2
npm corrompe archivos al instalar en
/mnt/e/(NTFS via WSL2).
Desarrollo activo en:/home/deivit/Projects/FileCage/(filesystem Linux)
Los fuentes se sincronizan aE:\Projects\FileCage\cuando sea necesario.
¶ 
Stack y Decisiones Tecnicas
| Item | Decision |
|---|---|
| Runtime | Node.js |
| Framework | Express |
| Docs | Swagger (swagger-jsdoc + swagger-ui-express) |
| Almacenamiento | Filesystem local — volumen montado del host |
| Contenerizacion | Solo Dockerfile (sin docker-compose) |
| Repo | Gitea interno (gitxub.neosolutions.com.ar) |
| Deploy | Contabo (154.12.252.27) |
| Subdominio | filecage.com |
| Puerto interno | 3301 (host) ? 3300 (container) |
¶ 
Docker — Comando de deploy
docker run -d \
--name filevault \
--restart unless-stopped \
-p 127.0.0.1:3300:3300 \
-v /data/filevault:/app/storage \
filevault:latest
¶ 
Autenticacion
X-Password: <contraseña>
Guardada con bcrypt en .meta.json dentro de cada carpeta.
¶ 
UID de Carpeta
- 8 caracteres | Charset:
A-Z(sinO) +0-9= 35 chars posibles - Ejemplos:
A3K9PX2M,0BF7NT1Z
¶ 
Endpoints
| Metodo | Path | Descripcion |
|---|---|---|
| POST | /folders |
Crear carpeta protegida |
| POST | /folders/:uid/files |
Subir archivo (max 100MB) |
| GET | /folders/:uid/files |
Listar archivos |
| GET | /folders/:uid/files/:filename |
Descargar archivo |
| DELETE | /folders/:uid/files/:filename |
Borrar archivo |
¶ 
Estructura del Proyecto
filevault/
+-- Dockerfile
+-- package.json
+-- .gitignore
+-- src/
¦ +-- index.js
¦ +-- routes/
¦ ¦ +-- folders.js
¦ +-- middleware/
¦ ¦ +-- auth.js
¦ +-- utils/
¦ ¦ +-- uid.js
¦ +-- swagger.js
+-- storage/ ? solo en dev; en prod = volumen montado
¶ Estructura de Datos (host)
/data/filevault/
+-- A3K9PX2M/
¦ +-- .meta.json ? { "password": "$2b$10$...", "created": "..." }
¦ +-- documento.pdf
+-- 0BF7NT1Z/
+-- .meta.json
+-- archivo.zip
¶ 
Codigos de Error
| Código | Situacion |
|---|---|
| 401 | Password incorrecta o header ausente |
| 404 | Carpeta o archivo no encontrado |
| 409 | Archivo ya existe con ese nombre |
| 413 | Archivo supera los 100 MB |
¶ 
Dependencias
{
"express": "^4.x",
"multer": "^1.x",
"bcrypt": "^5.x",
"swagger-jsdoc": "^6.x",
"swagger-ui-express": "^5.x"
}
Iniciado por Cloe 
— 2026-08-26
¶ 
Uso con curl
Base URL:
https://filecage.com
¶ 1. Crear una carpeta
curl -X POST https://filecage.com/folders \
-H "X-Password: tu-contraseña"
Respuesta:
{ "uid": "A3K9PX2M" }
¶ 2. Subir un archivo
curl -X POST https://filecage.com/folders/A3K9PX2M/files \
-H "X-Password: tu-contraseña" \
-F "file=@/ruta/a/tu/archivo.pdf"
Respuesta:
{ "name": "archivo.pdf", "size": 204800 }
¶ 3. Listar archivos
curl https://filecage.com/folders/A3K9PX2M/files \
-H "X-Password: tu-contraseña"
Respuesta:
{
"uid": "A3K9PX2M",
"files": [
{ "name": "archivo.pdf", "size": 204800, "uploaded": "2026-08-26T15:00:00.000Z" }
]
}
¶ 4. Descargar un archivo
curl https://filecage.com/folders/A3K9PX2M/files/archivo.pdf \
-H "X-Password: tu-contraseña" \
-o archivo-descargado.pdf
¶ 5. Borrar un archivo
curl -X DELETE https://filecage.com/folders/A3K9PX2M/files/archivo.pdf \
-H "X-Password: tu-contraseña"
Respuesta:
{ "deleted": "archivo.pdf" }
¶ Flujo completo de ejemplo
# 1. Crear carpeta
UID=$(curl -s -X POST https://filecage.com/folders \
-H "X-Password: mipass123" | python3 -c "import sys,json; print(json.load(sys.stdin)['uid'])")
echo "Carpeta creada: $UID"
# 2. Subir archivo
curl -s -X POST https://filecage.com/folders/$UID/files \
-H "X-Password: mipass123" \
-F "file=@documento.pdf"
# 3. Listar
curl -s https://filecage.com/folders/$UID/files \
-H "X-Password: mipass123"
# 4. Descargar
curl -s https://filecage.com/folders/$UID/files/documento.pdf \
-H "X-Password: mipass123" -o documento-descargado.pdf
# 5. Borrar
curl -s -X DELETE https://filecage.com/folders/$UID/files/documento.pdf \
-H "X-Password: mipass123"
¶ Codigos de error comunes
| HTTP | Causa | Solucion |
|---|---|---|
401 |
Header X-Password ausente o incorrecto |
Verificar la contraseña |
404 |
Carpeta o archivo no encontrado | Verificar el UID y el nombre del archivo |
409 |
Ya existe un archivo con ese nombre | Borrar el existente o renombrar el nuevo |
413 |
Archivo supera 100MB | Comprimir o partir el archivo |
¶ Clientes
- FileCage CLI Client — Binario Go para Windows y Linux. Permite usar la API desde la terminal con
filecage list/upload/download/delete.