Sync-in · Sovereign platform for file storage, sharing, synchronization, and collaboration.
TypeScript cloud-alternativecollaborationcollaborative-editingdropboxfile-serverfile-sharingfile-storagefile-syncfull-text-searchhomelabnextcloudon-premiseopen-sourceprivacy-firstprivate-cloudrealtimesecureself-hostedstorage-serverwebdav
doc(backend): completion for spaces and shares
johaven055a5e49c989
diff --git a/backend/src/applications/shares/shares.md b/backend/src/applications/shares/shares.mdindex 09257c56..4e1ee873 100644--- a/backend/src/applications/shares/shares.md+++ b/backend/src/applications/shares/shares.md@@ -3,6 +3,55 @@The `shares` module exposes existing storage through share aliases. A share does not copy its source and does not become the owner of the underlyingstorage.+## Access and permission model++Receiving and managing shares are separate application capabilities. `SHARES` allows a user or guest to browse `shares/<share-alias>/...`, while+`SHARES_ADMIN` allows an authorized user account to create, update, disable, and delete shares and their links. Effective membership can be granted+directly, through a group, or through a link pseudo-user.++Members can read an enabled share. Additional operations reuse the space permission model, except that `SHARE_INSIDE` does not apply:++| Operation | Backend permission | Meaning |+|-----------|--------------------|-----------------------------------------------------------|+| Add | `ADD` | Create, upload, copy, or move content into a directory |+| Modify | `MODIFY` | Edit content and manage locks |+| Delete | `DELETE` | Delete content or move it out of its current location |+| Share | `SHARE_OUTSIDE` | Create a child share or a link from the exposed content |++A move requires `DELETE` on the source and `ADD` on the destination. Permissions granted to members, groups, guests, links, and child shares are+intersected with the creator's effective permissions on the source. Personal content starts with the owner's full file permissions; content reached+through a collaborative space or parent share remains capped by that context.++The source provenance is required internally for authorization, quota, path, and deletion routing, but recipient-facing views must not expose whether+the source came from personal files or a collaborative space. Owner and administration views may expose the source context for management purposes.++## Share identity and lifecycle++A common share is addressed by its globally unique `alias`; `name` is the display name shown to recipients and may differ from the source name.+Description and enabled state also belong to the share definition. Disabling a share preserves its source, memberships, descendants, and settings but+makes the endpoint unavailable until it is enabled again.++File-backed shares retain source identity through `shares.fileId`, while gateway shares use `spaceRootId` or `externalPath`. Renaming or moving a+file-backed source within the same logical repository updates the existing file record, so the share remains attached without copying data. Permanently+deleting the source removes dependent share definitions through their database relations.++The share owner can manage the share and its descendant hierarchy. Managers of an originating collaborative space can also administer shares created+from that space. Deleting or disabling a share definition is distinct from deleting content while browsing the share; those behaviors are detailed+below.++## External locations++An administrator can expose an existing server directory as a root external share. The share stores the directory in `shares.externalPath`, has no+backing `fileId`, and sets `ownerId` to `null` because no managed user or native space owns that storage. No content is copied, and the share alias is+only the virtual entry point into the external directory.++External-share creation verifies that the path exists and that the operating-system account running the server can read and write it. These shares+are visible and manageable by administrators. Their canonical root owns the share-level quota and indexing configuration; nested shares preserve the+external provenance but reuse the highest ancestor's storage scope.++Because an external share has no managed storage owner, the current backend does not route deletions to the actor's personal trash. Content deleted+through the share is removed permanently according to the policy described below.+## Storage provenanceThe share keeps enough provenance to resolve the physical source and its managed storage owner:@@ -46,6 +95,20 @@ repository routing must all use the same canonical `files.shareExternalId`. A coIf the highest external ancestor cannot be resolved, the operation must fail before modifying the filesystem. It must not fall back to the immediateparent, the current descendant, or the authenticated actor.+## Quota routing++Quota enforcement follows the storage provenance rather than the actor or the share currently being browsed:++| Shared storage | Applied quota |+|-------------------------------------------|----------------------------------------------------|+| Personal files | Source owner's personal quota |+| Native-space files | Origin space quota |+| External root attached to a native space | Origin space quota |+| Root external share and its descendants | Highest external ancestor share quota |++Share-level `storageUsage`, `storageQuota`, and `storageIndexing` are meaningful only for the canonical external root. Descendant share rows may retain+the external path for resolution, but operations reuse the highest external ancestor and must not establish independent quota ownership.+## Child-share permission delegationCreating a child share requires the effective `SHARE_OUTSIDE` permission on its immediate parent. Requested member and link permissions are@@ -55,6 +118,20 @@ Member and link permissions are stored on each share. Permission removals on a pdelegation. New permissions on a parent do not automatically expand existing descendant grants. Removing a member from a parent can also remove childshares owned through that delegation unless another effective membership still grants the required share permission.+The owner of an ancestor share retains management visibility over descendant shares. Removing a member who created child shares removes the branches+owned through that delegation. Losing `SHARE_OUTSIDE` only blocks future delegation; existing child shares remain until explicitly removed or until+their parent membership or permission propagation invalidates them.++## Share links++A share link is represented by a link identity attached as a share member with its own effective permissions. Links created from a share are managed+from that share rather than from the global list of file-origin links. Deleting the share removes its associated links together with the memberships+that grant access.++Public-link validation combines the link and pseudo-user state. A link may be disabled, limited by an expiration date or access count, protected by a+password, and associated with a recipient name, email, and language. Successful file downloads or folder accesses increment its access counter. Link+permissions remain capped by the share permissions exactly like any other membership.+## Deleting a share and deleting shared contentDeleting a share definition removes the share, its memberships, and its child share definitions. It does not delete the source content from the@@ -97,5 +174,4 @@ scheduler. If the external location cannot be modified, the deletion fails insteThe permanent-deletion rule is the current policy until external trash is implemented as a first-class repository. Such a repository must beexplicitly addressable by the file browser and must define empty, restore, and retention lifecycles before external-share deletion can target it.-The managed trash layout and lifecycle are specified in-[`spaces.md`](../spaces/spaces.md).+The managed trash layout and lifecycle are specified in `spaces.md`.diff --git a/backend/src/applications/spaces/spaces.md b/backend/src/applications/spaces/spaces.mdindex 5b355217..23688239 100644--- a/backend/src/applications/spaces/spaces.md+++ b/backend/src/applications/spaces/spaces.md@@ -2,6 +2,51 @@The `spaces` module manages collaborative spaces, anchored roots, external roots, and the logical repositories used to browse their files and trash.+## Collaboration and access model++A collaborative space is an independent ownership and permission boundary. Its managed files, trash, quota, content-indexing setting, members, roots,+and shares are attached to the space rather than to an individual member. Access requires both the corresponding application permission and an+effective membership obtained directly, through a group, as a guest, or through a space link.++Members can read an accessible space. Additional operations are granted independently:++| Operation | Backend permission | Meaning |+|-----------|--------------------|---------------------------------------------------------|+| Add | `ADD` | Create, upload, copy, or move content into a location |+| Modify | `MODIFY` | Edit content and manage locks |+| Delete | `DELETE` | Delete content or move it out of its current location |+| Anchor | `SHARE_INSIDE` | Add personal content as a virtual root inside the space |+| Share | `SHARE_OUTSIDE` | Create a share from content exposed by the space |++A move requires `DELETE` on the source and `ADD` on the destination. Space managers receive every space-level operation and can manage the space, its+members, roots, quota, indexing setting, and shares. This does not bypass the permissions attached to an anchored root.++## Anchored root model++An anchored root exposes a file or directory from a member's personal files at the top level of a collaborative space. The `spaces_roots.fileId`+reference preserves the source identity: no content is copied and the personal repository remains the storage owner. Moving or renaming the source+inside that repository updates the same file record, so the anchor remains valid.++The root `alias` is its unique path segment inside the space, while `name` is its display name. Both can differ from the source name without renaming+the backing resource. Removing the root only removes this virtual exposure; it does not delete the source content. The anchored endpoint itself is+protected from file deletion, while its children remain subject to the effective file permissions described below.++Anchoring requires `SHARE_INSIDE`. The permissions effective below the root are the intersection of the member's space permissions and the root+permissions defined by its owner. Denial from either side denies the operation, including for space managers. Creating a share from anchored content+likewise requires `SHARE_OUTSIDE` in both permission sets, and a member cannot delegate permissions they do not effectively hold.++Anchored roots are first-class virtual locations for browser, search, WebDAV, synchronization, comments, and favorites consumers. These consumers must+resolve the backing file identity and canonical storage scope instead of treating the root alias as a physical directory.++Removing an anchored root also removes shares tied to that root, including their descendant shares. Roots owned by a member are removed when that+member leaves the space. For a regular member, losing `SHARE_INSIDE` blocks further root management, while losing `SHARE_OUTSIDE` prevents new shares;+neither permission loss removes the corresponding existing roots or shares by itself.++## Space lifecycle++A manager can deactivate a space, while an administrator can delete it immediately. A disabled space is inaccessible to its members and its trash is+not browsable. Reactivation restores access before expiry; otherwise the scheduler permanently removes a space after 30 disabled days.+## Managed space storageA native space has a managed home under the configured spaces path:@@ -27,6 +72,20 @@ An external root is only a view of an existing filesystem location. Sync-in doesIn particular, `<external-root>/.trash/` is not part of the storage layout. Such a directory would not correspond to a logical trash repository, sothe trash list, browser, restore operations, and retention scheduler could not discover or empty it.+## External locations++An external location is an existing server directory exposed at the top level of a collaborative space through a `spaces_roots.externalPath` record.+It has no backing `fileId` and must not be confused with a member-owned anchor from personal files. No data is copied into the managed space home; the+root alias remains a virtual path segment while all content stays under the configured external directory.++Only an administrator can register an external location. The administration preflight verifies that the path exists and that the operating-system+account running the server can read and write it. Those filesystem permissions must remain valid after registration. The raw external path is hidden+from non-administrator space responses.++External-root usage is included in the native space's `storageUsage` together with its managed home and other external roots. The native space quota+therefore remains authoritative even though the content is physically outside that home. Deleting a child from the external location moves it into+the native space trash, removes its external-root storage identity, and makes it subject to the space's trash permissions and retention policy.+## Logical trash repositoriesTrash repositories are addressed without a root level:@@ -66,12 +125,19 @@ deleted permanently, regardless of the actor type. There is no fallback to### Trash permissions and anchored rootsAnchored root endpoints are virtual and cannot be deleted through file operations. Operations on their children use the intersection of the member's-space permissions and the root permissions.+space permissions and the root permissions. This protection applies to the endpoint exposed by the space; it does not make the backing source+immutable in its original repository.When a root is anchored to a file or directory in a user's personal storage, deleting one of its children moves that entry to the personal trash ofthe root owner. It does not enter the native space trash, and other space members do not gain control over it through their space permissions. Nativespace files that are not anchored continue to use the native space trash.+An anchored descendant is resolvable only while it remains in the same canonical storage scope as the backing root. This scope includes `ownerId`,+`spaceId`, `spaceExternalRootId`, `shareExternalId`, and `inTrash`, in addition to the descendant path. Moving a child to the owner's personal trash+changes that scope and places it in a different logical and physical repository. The child therefore leaves the anchored tree immediately: the root+endpoint remains active, but the deleted child cannot be reached through it or through the native space trash. Only an actor with access to the+owner's personal trash can resolve the moved entry there.+External roots are the exception. Deleting a child from an external root still requires the effective `DELETE` permission in the source context, butthe entry then becomes owned by the native space trash. Its external-root identity and root permissions are not retained there, so subsequent trashoperations use the space permissions. A member with `DELETE` on the space can therefore move the entry out of trash or delete it permanently. Moving