Skip to content

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 ​

ActionWho
Operate space=platformPlatform super admin only; bypasses plan entitlements
Operate space=tenantA plan with object_storage_enabled and (implicit OWNER, an explicit grant, or a secret key sk_ / api_key)
Manage grants / read limitsOWNER with entitlement only. A MEMBER with an operation grant → 403 on grants and GET /limits
Super admin → tenant space403 (it does not browse tenant buckets here)
Tenant → platform space403
Base plan (without object_storage_enabled)403 OBJECT_STORAGE_NOT_ENTITLED deny-all on tenant operations
Pro / Max planFeature on (ladder + resale)
Routes under backups/404 without revealing existence
Nonexistent route / outside the space404 / 400
Consuming a temporary linkAnyone 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 /limits and 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.

ActorCan it operate the tenant bucket?
OWNER with entitlementYes, without a grant row (implicit)
ADMIN / MEMBER / VIEWER with grantYes
ADMIN / MEMBER / VIEWER without grant403 OBJECT_STORAGE_GRANT_MISSING, even when the plan has object_storage_enabled
After revoking the grant403 OBJECT_STORAGE_GRANT_MISSING again
Secret key (tokenType=api_key)Yes, tenant + entitlement only; it requires no per-user grant
Super AdminDoes 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.

EventWhenData (no secrets)
object-storage.operate-grantedAn OWNER grants a member permission (only when a new row is created)space tenant, company, granted user, actor
object-storage.operate-revokedAn 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:

KeyUse
object_storage_enabledBoolean feature — Base off / Pro+ on
object_storage_max_file_bytesPer-file cap when configured
object_storage_quota_bytesSpace quota when configured
object_storage_allowed_typesAllow/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_bytes when granted and > 0; otherwise the soft max of 50 MB.
  • Type: only when the LIST entitlement is active (mode allow|deny).
  • Quota: only with platform storage (usesPlatformStorage); BYOK applies no quota. The check is atomic through the object_storage_usage counter: 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 ​

MethodRouteAuthDescription
GET/object-storage/:space/objects?path=BearerLists objects/folders at the path
POST/object-storage/:space/objectsBearerUploads a file (multipart: file, optional path, overwrite=true to replace). No silent overwrite → 409; validations apply
GET/object-storage/:space/objects/content?path=BearerDownloads the object
DELETE/object-storage/:space/objects?path=BearerDeletes a file or folder (recursive)
POST/object-storage/:space/objects/moveBearerRenames/moves inside the space (from, to). No silent overwrite → 409
POST/object-storage/:space/foldersBearerCreates a listable empty folder (path). Idempotent when the folder exists; 409 when a file occupies that path
POST/object-storage/:space/temp-linksBearerIssues a public temporary link (default TTL 48 h). No auth → 401
DELETE/object-storage/:space/temp-links/:idBearerRevokes the link. No auth → 401; cross-tenant revoke → 404
GET/object-storage/public/temp-links/:tokenPublicDownloads 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/permissionsBearer OWNERLists the active company's operation grants
PUT/object-storage/tenant/permissions/:userIdBearer OWNERGrants the operation permission to a member (404 when not a member). Idempotent
DELETE/object-storage/tenant/permissions/:userIdBearer OWNERRevokes the grant (204, idempotent)
GET/object-storage/tenant/limitsBearer OWNEREffective 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:

json
{ "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 storage family → platform/env → local.
  • ftp / gcs: rejected at configuration/resolution with 400 STORAGE_PROVIDER_UNAVAILABLE; they are not silently mapped to local.
  • BYOK / a local seed or another unknown type without a remote adapter: the backend uses local disk but keeps usesPlatformStorage=false and the BYOK source/providerId, so the platform quota does not apply. The localDefault fallback (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:

CodeMeaning
OBJECT_STORAGE_NOT_ENTITLEDPlan without object_storage_enabled
OBJECT_STORAGE_GRANT_MISSINGJWT 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)