feat(storage)!: complete container/folder/file authorization

CHANGELOG.md

@@ -2,6 +2,16 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+## [Unreleased]
+
+### ⚠ BREAKING CHANGES
+
+* **storage:** Client APIs no longer create missing containers (404). An omitted folder now resolves to a personal `cnd_<userId>/` folder. Client list-files is deferred.
+
+### Features
+
+* **storage:** complete filesystem-shaped ReBAC for Container, Folder, and File ([#1173](https://github.com/ConduitPlatform/Conduit/issues/1173))
+
 ## [0.17.0-alpha.6](https://github.com/ConduitPlatform/Conduit/compare/v0.17.0-alpha.5...v0.17.0-alpha.6) (2026-07-26)
 
 

modules/storage/README.md

@@ -0,0 +1,24 @@
+# Storage
+
+Authorization for containers, folders, and files. Client list-files is deferred.
+
+## Client breaking changes
+
+These apply to Storage Client routes and gRPC calls that use the user file handlers.
+
+- **Missing containers are not created.** Creating or updating a file with a container that does not already exist returns `404 Not Found`. `allowContainerCreation` still only affects Admin implicit container creation.
+- **Omitted folder becomes a personal folder.** If `folder` is omitted on Client file create, Storage uses `cnd_<userId>/`. Passing `/` still stores at the container root.
+- **Personal-folder squat is denied.** Creating a missing `cnd_<otherUserId>/` path returns `403 Permission Denied`. A user may create their own `cnd_<userId>/`. If another user's personal root already exists, normal folder edit checks apply.
+
+Admin-only container create remains available. Public file reads without auth, module schema ownership, and existing public URI / CDN / content-disposition / local URL upload behavior are unchanged.
+
+## Authorization tree
+
+When `authorization.enabled` is true, Storage registers `Container`, `Folder`, and `File` resources and maintains owner relations that follow the path:
+
+- A container may own first-level folders, or files stored at `/`.
+- A folder owns nested folders and files.
+- The default container is never owned. It is created on both the database and the storage provider if missing.
+- An optional `scope` (for example `Team:<id>`) is attached as an extra owner when provided. Admin folder create without scope only attaches the container as the first-folder owner.
+
+Folder delete removes nested folders/files and all of their relations. Container delete pages those cleanups and also clears `Container` relations.

modules/storage/package.json

@@ -30,7 +30,7 @@
     "prepare": "npm run build",
     "build:docker": "docker build -t ghcr.io/conduitplatform/storage:latest -f ./Dockerfile ../../ && docker push ghcr.io/conduitplatform/storage:latest",
     "generateTypes": "sh build.sh",
-    "test": "tsc -p tsconfig.test.json && node --test dist-test/adapter/StorageParamAdapter.test.js dist-test/migrations/fileUriMigration.test.js dist-test/providers/aws/acl.test.js dist-test/providers/google/folderMarkers.test.js dist-test/providers/google/deleteFolder.test.js dist-test/providers/google/publicAccess.test.js dist-test/utils/filePrivacy.test.js"
+    "test": "tsc -p tsconfig.test.json && node --test dist-test/adapter/StorageParamAdapter.test.js dist-test/migrations/fileUriMigration.test.js dist-test/providers/aws/acl.test.js dist-test/providers/google/folderMarkers.test.js dist-test/providers/google/deleteFolder.test.js dist-test/providers/google/publicAccess.test.js dist-test/utils/filePrivacy.test.js dist-test/authz/helpers.test.js dist-test/authz/relations.test.js dist-test/authz/folders.test.js dist-test/authz/cascade.test.js dist-test/authz/bootstrap.test.js dist-test/handlers/file.authz.test.js"
   },
   "keywords": [],
   "author": "",

modules/storage/src/Storage.ts

@@ -50,7 +50,8 @@ import {
   type ImportResult,
 } from '@conduitplatform/module-tools';
 import { StorageParamAdapter } from './adapter/StorageParamAdapter.js';
-import { FileResource } from './authz/index.js';
+import { ContainerResource, FileResource, FolderResource } from './authz/index.js';
+import { ensureDefaultContainer } from './authz/bootstrap.js';
 import { AdminFileHandlers } from './admin/adminFile.js';
 import { randomBytes } from 'node:crypto';
 import { fileURLToPath } from 'node:url';
@@ -248,9 +249,11 @@ export default class Storage extends ManagedModule<Config> {
         this._storageAuthzResourceDispose?.();
         this._storageAuthzResourceDispose = this.grpcSdk.oncePeerUp(
           'authorization',
-          () => {
+          async () => {
             this._storageAuthzResourceDispose = null;
-            this.grpcSdk.authorization!.defineResource(FileResource);
+            await this.grpcSdk.authorization!.defineResource(ContainerResource);
+            await this.grpcSdk.authorization!.defineResource(FolderResource);
+            await this.grpcSdk.authorization!.defineResource(FileResource);
           },
         );
       } else {
@@ -269,6 +272,7 @@ export default class Storage extends ManagedModule<Config> {
       });
       this._fileHandlers.updateProvider(this.storageProvider);
       this._adminFileHandlers.updateProvider(this.storageProvider);
+      await ensureDefaultContainer(this.storageProvider);
       // Run the public container migration once after provider is configured
       if (!this.publicContainerMigrationRan && provider !== 'local') {
         this.publicContainerMigrationRan = true;