Object storage
What this module does
It exposes a free bucket (object space) for the platform and for each tenant, operable with listing, upload, download, delete, rename/move, folder creation and public temporary links. It uses the storage provider already resolved (the storage family: S3 / local; ftp/gcs are rejected at configuration/resolution until a connector exists).
Database backups live in a different space (backups/) and are not listed or operated through this API.
For the NimoApps runtime, the tenant space is partitioned by the server-authorized environment: objects/tenants/{companyId}/environments/{environmentId}/. The existing administrative space keeps the historical root objects/tenants/{companyId}/; runtime operations do not fall back to it when the authorized environment is missing. Grants, temporary links and file references are bound to the environment too. A legacy administrative grant grants no runtime access, and preview cannot reference production files.
Who can do what
| Action | Who |
|---|---|
Operate space=platform | Platform super admin only; bypasses plan entitlements |
Operate space=tenant | A plan with object_storage_enabled and (implicit OWNER, an explicit grant, or a secret key sk_ / api_key) |
| Manage grants / read limits | OWNER with entitlement only. A MEMBER with an operation grant → 403 on grants and GET /limits |
| Super admin → tenant space | 403 (it does not browse tenant buckets here) |
| Tenant → platform space | 403 |
Base plan (without object_storage_enabled) | 403 OBJECT_STORAGE_NOT_ENTITLED deny-all on tenant operations |
| Pro / Max plan | Feature on (ladder + resale) |
Routes under backups/ | 404 without revealing existence |
| Nonexistent route / outside the space | 404 / 400 |
| Consuming a temporary link | Anyone with the token (no login) while it has not expired nor been revoked — deleting or moving the object also revokes it |
Temporary links, entitlements with their validations, operation grants with
GET /limitsand the TypeScript SDK are in force. The Angular dashboard consumes the SDK only.
Operation permissions
A single boolean permission covers listing, uploading, downloading, deleting, moving, creating folders and issuing or revoking temporary links.
| Actor | Can it operate the tenant bucket? |
|---|---|
| OWNER with entitlement | Yes, without a grant row (implicit) |
| ADMIN / MEMBER / VIEWER with grant | Yes |
| ADMIN / MEMBER / VIEWER without grant | 403 OBJECT_STORAGE_GRANT_MISSING, even when the plan has object_storage_enabled |
| After revoking the grant | 403 OBJECT_STORAGE_GRANT_MISSING again |
Secret key (tokenType=api_key) | Yes, tenant + entitlement only; it requires no per-user grant |
| Super Admin | Does not operate the tenant space; there are no platform grants |
The OWNER (with object_storage_enabled) grants and revokes. The grant does not grant reading configuration or limits: that stays reserved for the OWNER.
Permission audit
Every grant or revocation of the operation permission emits a domain event that the audit module writes to the structured log (actor, company, space and affected user; no secrets). The grant row is not a history: revocation deletes it, so the event is the durable record of who revoked whom. Full list in System events.
| Event | When | Data (no secrets) |
|---|---|---|
object-storage.operate-granted | An OWNER grants a member permission (only when a new row is created) | space tenant, company, granted user, actor |
object-storage.operate-revoked | An OWNER revokes an existing grant (after deleting the row) | space tenant, company, revoked user, actor |
A revocation with no previous row and a re-grant when the permission already existed emit no event (idempotent).
Assistant integration (/ AI-FILES-001)
The assistant's shareable catalogue can list names and metadata from the active company's space, create folders, move files, delete files or folders recursively and create or revoke temporary links. Every mutation requires an authorized person to review and confirm the path or the link.
The handler pins space=tenant: the model cannot select the company, the space, the user or the grant. Every operation rechecks ai_assistants, object_storage_enabled and the current Object Storage permission (implicit OWNER or a live grant); the service itself resolves the provider and normalizes paths, including rejecting .. and backups/. A nonexistent resource returns a generic result with no name or metadata; entitlement or grant denials keep their stable codes.
The chat receives no bytes to upload and returns no binary content. To download a file it can create, with explicit confirmation, a public link for a single object; it expires after 48 hours by default and can be revoked. The revoke option does not enumerate someone else's links and is limited to the active company.
Entitlements and upload validations
Catalogue keys:
| Key | Use |
|---|---|
object_storage_enabled | Boolean feature — Base off / Pro+ on |
object_storage_max_file_bytes | Per-file cap when configured |
object_storage_quota_bytes | Space quota when configured |
object_storage_allowed_types | Allow/deny LIST of extensions and/or MIME |
Current behaviour:
- SA platform: does not consult the plan gate; only a soft operational max of 50 MB.
- Tenant: requires
object_storage_enabled(the effective resale plan when assigned; otherwise the platform entitlement). - Size: uses
object_storage_max_file_byteswhen granted and > 0; otherwise the soft max of 50 MB. - Type: only when the LIST entitlement is active (
modeallow|deny). - Quota: only with platform storage (
usesPlatformStorage); BYOK applies no quota. The check is atomic through theobject_storage_usagecounter: two concurrent uploads cannot exceed the limit. - Numeric seeds of quota / max-file in the ladder: deferred — the keys exist for enforcement once configured, without inventing GB figures.
Operations
| Method | Route | Auth | Description |
|---|---|---|---|
GET | /object-storage/:space/objects?path= | Bearer | Lists objects/folders at the path |
POST | /object-storage/:space/objects | Bearer | Uploads a file (multipart: file, optional path, overwrite=true to replace). No silent overwrite → 409; validations apply |
GET | /object-storage/:space/objects/content?path= | Bearer | Downloads the object |
DELETE | /object-storage/:space/objects?path= | Bearer | Deletes a file or folder (recursive) |
POST | /object-storage/:space/objects/move | Bearer | Renames/moves inside the space (from, to). No silent overwrite → 409 |
POST | /object-storage/:space/folders | Bearer | Creates a listable empty folder (path). Idempotent when the folder exists; 409 when a file occupies that path |
POST | /object-storage/:space/temp-links | Bearer | Issues a public temporary link (default TTL 48 h). No auth → 401 |
DELETE | /object-storage/:space/temp-links/:id | Bearer | Revokes the link. No auth → 401; cross-tenant revoke → 404 |
GET | /object-storage/public/temp-links/:token | Public | Downloads the object scoped to the link. Requires no grant. Expired/revoked → 403; deleting or moving the object revokes the link (not reusable after re-uploading to the same path) |
GET | /object-storage/tenant/permissions | Bearer OWNER | Lists the active company's operation grants |
PUT | /object-storage/tenant/permissions/:userId | Bearer OWNER | Grants the operation permission to a member (404 when not a member). Idempotent |
DELETE | /object-storage/tenant/permissions/:userId | Bearer OWNER | Revokes the grant (204, idempotent) |
GET | /object-storage/tenant/limits | Bearer OWNER | Effective read-only limits (objectStorageEnabled, quotaBytes, maxFileBytes, allowedTypes, skipQuota). A MEMBER with a grant → 403. There is no limits write API |
:space is platform or tenant.
Body for creating a link:
{ "path": "docs/report.pdf", "ttlHours": 48 }ttlHours is optional (default 48, maximum 720). The response includes id, token, url, expiresAt. The link does not authenticate the bearer as a tenant member: it only delivers that one object.
Storage
Resolution through ObjectSpaceResolutionService:
- Platform: built-in/platform S3 provider → S3 env → local.
- Tenant: active BYOK of the
storagefamily → platform/env → local. ftp/gcs: rejected at configuration/resolution with 400STORAGE_PROVIDER_UNAVAILABLE; they are not silently mapped to local.- BYOK / a
localseed or another unknown type without a remote adapter: the backend uses local disk but keepsusesPlatformStorage=falseand the BYOKsource/providerId, so the platform quota does not apply. ThelocalDefaultfallback (platform quota) applies only when the origin really is platform storage.
Logical prefixes:
- Platform:
objects/platform/… - Tenant:
objects/tenants/{companyId}/…
Absolute public URL (optional): if API_PUBLIC_URL is defined, url in the creation response is absolute; otherwise it is the relative path /object-storage/public/temp-links/{token}.
SDK
Parity in @nimobase/sdk (node + browser) through client.objectStorage: list, upload, download, delete, move, createFolder, createTempLink, revokeTempLink, downloadPublicTempLink, listGrants, grant, revoke, getLimits. upload accepts { overwrite: true } to replace; omitted → 409 when the path already exists. Authz, plan, MEMBER grant and backup isolation are enforced on the server. Tenant operations accept the SDK's runtime context through applicationDsl.setRuntimeContext({ projectId, environmentId }): the server validates project, company, membership and assigned release before resolving the environment. Without selectors the existing tenant space is preserved; grants, limits and anonymous token consumption stay outside runtime. The Angular host must not open a parallel HTTP client for these operations.
Tenant-space 403s arrive in NimobaseError.code (the Nest error body) as stable codes — do not parse the English message:
| Code | Meaning |
|---|---|
OBJECT_STORAGE_NOT_ENTITLED | Plan without object_storage_enabled |
OBJECT_STORAGE_GRANT_MISSING | JWT without an operation grant |
Helpers: isObjectStorageNotEntitledError / isObjectStorageGrantMissingError (also in NimobaseErrorCodes).
See the SDK on your server and in the browser.
Out of scope (later tasks)
- Angular dashboard
- Antivirus
- A limits/quota write API (the numbers belong to the plan)