Skip to content

Almacenamiento de objetos ​

¿Qué hace este módulo? ​

Expone un bucket libre (espacio de objetos) para la plataforma y para cada tenant, operable con listado, subida, descarga, borrado, renombrado/movimiento, creación de carpetas y enlaces temporales públicos. Usa el proveedor de storage ya resuelto (familia storage de : S3 / local; ftp/gcs se rechazan en configuración/resolución hasta que exista conector).

Los respaldos de BBDD viven en un espacio distinto (backups/) y no se listan ni operan desde esta API.

Para el runtime NimoApps, el espacio de tenant se particiona por el entorno autorizado por el servidor: objects/tenants/{companyId}/environments/{environmentId}/. El espacio administrativo existente conserva la raíz histórica objects/tenants/{companyId}/; las operaciones runtime no recurren a ella si falta el entorno autorizado. Los grants, enlaces temporales y referencias de archivo también quedan ligados al entorno. Un grant administrativo legado no concede acceso al runtime, y preview no puede referenciar archivos de producción.

Ver .

Quién puede hacer qué ​

AcciónQuién
Operar space=platformSolo super admin de plataforma; bypass de entitlements de plan
Operar space=tenantPlan con object_storage_enabled y (OWNER implícito, grant explícito, o clave secreta sk_ / api_key)
Gestionar grants / leer límitesSolo OWNER con entitlement. MEMBER con grant de operación → 403 en grants y GET /limits
Super admin → espacio tenant403 (no explora buckets de tenants aquí)
Tenant → espacio platform403
Plan Base (sin object_storage_enabled)403 OBJECT_STORAGE_NOT_ENTITLED deny-all en operaciones tenant
Plan Pro / MaxFeature on (ladder + resale)
Rutas bajo backups/404 sin revelar existencia
Ruta inexistente / fuera de espacio404 / 400
Consumir enlace temporalCualquiera con el token (sin login) mientras no caduque ni se revoque — borrar/mover el objeto también revoca

Los enlaces temporales, los entitlements con sus validaciones, los grants de operación con GET /limits y el SDK TypeScript están en vigor. El panel Angular consume solo el SDK.

Permisos de operación ​

Un único permiso booleano cubre listar, subir, descargar, borrar, mover, crear carpeta y emitir/revocar enlaces temporales.

Actor¿Puede operar el bucket tenant?
OWNER con entitlementSí, sin fila de grant (implícito)
ADMIN / MEMBER / VIEWER con grantSí
ADMIN / MEMBER / VIEWER sin grant403 OBJECT_STORAGE_GRANT_MISSING, aunque el plan tenga object_storage_enabled
Tras revocar el grant403 OBJECT_STORAGE_GRANT_MISSING de nuevo
Clave secreta (tokenType=api_key)Sí, solo tenant + entitlement; no exige grant por usuario
Super AdminNo opera espacio tenant; no hay grants de plataforma

El OWNER (con object_storage_enabled) concede y revoca. El grant no otorga lectura de configuración/límites: eso queda reservado al OWNER.

Auditoría de permisos ​

Cada concesión o revocación de permiso de operación genera un evento de dominio que el módulo de auditoría deja en el log estructurado (actor, empresa, espacio y usuario afectado; sin secretos). La fila del grant no es un historial: al revocar se borra, así que el evento es el registro durable de quién revocó a quién. Lista completa en Eventos del sistema.

EventoCuándoDatos (sin secretos)
object-storage.operate-grantedOWNER concede permiso a un miembro (solo si se crea fila nueva)espacio tenant, empresa, usuario concedido, actor
object-storage.operate-revokedOWNER revoca un grant existente (después de borrar la fila)espacio tenant, empresa, usuario revocado, actor

Una revocación sin fila previa y un re-grant cuando el permiso ya existía no emiten evento (idempotentes).

Integración con el asistente (/ AI-FILES-001) ​

El catálogo compartible del asistente puede listar nombres y metadatos del espacio de la empresa activa, crear carpetas, mover archivos, borrar archivos o carpetas recursivamente y crear/revocar enlaces temporales. Cada mutación requiere que una persona autorizada revise y confirme la ruta o el enlace.

El handler fija space=tenant: el modelo no puede seleccionar empresa, espacio, usuario ni grant. En cada operación se vuelven a comprobar ai_assistants, object_storage_enabled y el permiso actual de Object Storage (OWNER implícito o grant vigente); el propio servicio resuelve el proveedor y normaliza rutas, incluidos los rechazos de .. y backups/. Un recurso inexistente devuelve un resultado genérico sin nombre ni metadatos; las denegaciones de entitlement o grant conservan sus códigos estables.

El chat no recibe bytes para subir ni devuelve contenido binario. Para descargar un archivo puede crear, con confirmación explícita, un enlace público de un solo objeto; caduca en 48 horas por defecto y se puede revocar. La opción de revocar no enumera enlaces ajenos y queda limitada a la empresa activa.

Entitlements y validaciones de subida ​

Claves de catálogo:

ClaveUso
object_storage_enabledFeature boolean — Base off / Pro+ on
object_storage_max_file_bytesTope por fichero cuando está configurado
object_storage_quota_bytesCuota del espacio cuando está configurada
object_storage_allowed_typesLIST allow/deny de extensiones y/o MIME

Comportamiento actual:

  • SA platform: no consulta el gate de plan; solo soft max operativo de 50 MB.
  • Tenant: exige object_storage_enabled (resale efectivo si hay asignación ; si no, entitlement de plataforma).
  • Tamaño: usa object_storage_max_file_bytes si está concedido y > 0; si no, soft max 50 MB.
  • Tipo: solo si la LIST entitlement está activa (mode allow|deny).
  • Cuota: solo con storage de plataforma (usesPlatformStorage); BYOK no aplica cuota. La comprobación es atómica vía contador object_storage_usage: dos subidas concurrentes no pueden superar el límite.
  • Seeds numéricos de cuota / max-file en el ladder: diferidos las claves existen para enforcement cuando se configuren, sin inventar cifras GB.

Operaciones ​

MétodoRutaAuthDescripción
GET/object-storage/:space/objects?path=BearerLista objetos/carpetas de la ruta
POST/object-storage/:space/objectsBearerSube fichero (multipart: file, path opcional, overwrite=true para reemplazar). Sin sobrescritura silenciosa → 409; validaciones
GET/object-storage/:space/objects/content?path=BearerDescarga el objeto
DELETE/object-storage/:space/objects?path=BearerBorra fichero o carpeta (recursivo)
POST/object-storage/:space/objects/moveBearerRenombra/mueve dentro del espacio (from, to). Sin sobrescritura silenciosa → 409
POST/object-storage/:space/foldersBearerCrea carpeta vacía listable (path). Idempotente si la carpeta ya existe; 409 si un fichero ocupa esa ruta
POST/object-storage/:space/temp-linksBearerEmite enlace temporal público (TTL default 48 h). Sin auth → 401
DELETE/object-storage/:space/temp-links/:idBearerRevoca el enlace. Sin auth → 401; revoke cross-tenant → 404
GET/object-storage/public/temp-links/:tokenPúblicoDescarga el objeto acotado al enlace. No exige grant. Caducado/revocado → 403; borrar o mover el objeto revoca el enlace (no reutilizable tras re-subir en la misma ruta)
GET/object-storage/tenant/permissionsBearer OWNERLista grants de operación de la empresa activa
PUT/object-storage/tenant/permissions/:userIdBearer OWNERConcede el permiso de operación a un miembro (404 si no es miembro). Idempotente
DELETE/object-storage/tenant/permissions/:userIdBearer OWNERRevoca el grant (204, idempotente)
GET/object-storage/tenant/limitsBearer OWNERLímites efectivos de solo lectura (objectStorageEnabled, quotaBytes, maxFileBytes, allowedTypes, skipQuota). MEMBER con grant → 403. No hay API de escritura de límites

:space es platform o tenant.

Body de creación de enlace:

json
{ "path": "docs/report.pdf", "ttlHours": 48 }

ttlHours es opcional (default 48, máx. 720). La respuesta incluye id, token, url, expiresAt. El enlace no autentica al portador como miembro del tenant: solo entrega ese objeto.

Almacenamiento ​

Resolución vía ObjectSpaceResolutionService:

  • Plataforma: provider built-in/plataforma S3 → env S3 → local.
  • Tenant: BYOK activo de familia storage → platform/env → local.
  • ftp / gcs: rechazados en configuración/resolución con 400 STORAGE_PROVIDER_UNAVAILABLE no se mapean en silencio a local.
  • BYOK / seed local u otro tipo desconocido sin adaptador remoto: el backend usa disco local pero mantiene usesPlatformStorage=false y el source/providerId del BYOK, de modo que la cuota de plataforma no se aplica. El fallback localDefault (cuota de plataforma) solo aplica cuando el origen es realmente storage de plataforma.

Prefijos lógicos:

  • Plataforma: objects/platform/…
  • Tenant: objects/tenants/{companyId}/…

URL pública absoluta (opcional): si API_PUBLIC_URL está definida, url en la respuesta de creación es absoluta; si no, es una ruta relativa /object-storage/public/temp-links/{token}.

SDK ​

Paridad en @nimobase/sdk (node + browser) vía client.objectStorage: list, upload, download, delete, move, createFolder, createTempLink, revokeTempLink, downloadPublicTempLink, listGrants, grant, revoke, getLimits. upload acepta { overwrite: true } para reemplazar; omitido → 409 si la ruta ya existe. Authz, plan, grant de MEMBER y aislamiento de respaldos se aplican en el servidor. Las operaciones tenant aceptan el contexto runtime del SDK mediante applicationDsl.setRuntimeContext({ projectId, environmentId }): el servidor valida proyecto, empresa, membresía y release asignado antes de resolver el entorno. Sin selectores se conserva el espacio tenant existente; grants, límites y consumo anónimo de tokens no entran en runtime. El host Angular no debe abrir un cliente HTTP paralelo para estas operaciones.

Los 403 de espacio tenant llegan en NimobaseError.code (cuerpo Nest error) como códigos estables — no parsear el message en inglés:

CódigoSignificado
OBJECT_STORAGE_NOT_ENTITLEDPlan sin object_storage_enabled
OBJECT_STORAGE_GRANT_MISSINGJWT sin grant de operación

Helpers: isObjectStorageNotEntitledError / isObjectStorageGrantMissingError (también en NimobaseErrorCodes).

Ver el SDK en tu servidor y el SDK en el navegador.

Fuera de alcance (tareas posteriores) ​

  • Panel Angular
  • Antivirus
  • API de escritura de límites/cuota (los números los posee el plan)