feat: add container-specific permissions and immutable flag

[flash7777]

Summary

This PR adds container-specific permissions and an immutable (freeze) attribute to the CS3 storage provider API.

New fields in ResourcePermissions

• delete_container (field 21): delete permission for containers only, independent of file delete
• move_container (field 22): move/rename permission for containers only, independent of file move

New attribute in ResourceInfo

• immutable (field 20): persistent boolean attribute (xattr) — when true, resource cannot be modified/deleted/moved/renamed. For containers, also prevents creation of new children.

New RPCs in ProviderAPI

• SetImmutable: freezes a resource (manager/admin only)
• UnsetImmutable: unfreezes a resource (manager/admin only)

Motivation

We are developing an EDMS layer for German municipalities on top of OpenCloud/Reva. Core requirement: protecting file plan (Aktenplan) directory structures while allowing users to work freely with documents inside them.

The current API cannot express "users may delete files but not directories" — delete and move apply to both equally. And there is no persistent freeze/immutable concept (locks are temporary).

See docs/proposals/container-permissions-and-immutable.md for the full proposal.

Note on field 20

Field 20 in ResourceInfo is also targeted by #190 (Status). We have commented there to coordinate. We believe immutable and status serve different purposes (persistent admin attribute vs. transient processing state) and deserve separate fields.

Backward compatibility

All changes are additive. When new permission fields are not set, implementations fall back to existing delete/move behavior. Existing clients continue to work unchanged.

Related

• Reva ACL implementation: feat: add ACL support for container-specific permissions reva#5628
• Field 20 coordination: Add Status to ResourceInfo #190

[flash7777]

Context: Why we need this

We are currently developing an EDMS (Electronic Document Management System) layer on top of OpenCloud/Reva for German municipalities and public administration (Kommunalverwaltungen).

In this domain, file plans (Aktenpläne) are a fundamental concept — rigid, hierarchical directory structures (typically 4 levels deep) that must remain stable over years or even decades. Users work within this structure daily: they create, edit, and manage documents, but the structure itself must not be accidentally (or intentionally) altered by regular users.

Today, the CS3 permission model offers no way to express this. The delete and move permissions apply equally to files and containers. An editor who can delete a misplaced PDF can also delete an entire department folder — there is no middle ground.

The three additions in this proposal — delete_container, move_container, and immutable — are small in scope but would be a significant improvement for real-world DMS and records management use cases. They allow administrators to protect directory structures while giving users full flexibility to work with documents.

We believe this benefits not just our EDMS project, but any CS3-based deployment where directory structures carry organizational meaning — universities, research institutions, enterprises, and public sector organizations alike.

We are happy to contribute the implementation work in Reva (see cs3org/reva#5628) and would appreciate feedback from the community on the proposed API design.

[flash7777]

Quick note: The commits mention "Claude" as co-author — this just means we used Claude Code (AI coding assistant) as tooling support during development. The proposal and its rationale are entirely ours, based on real requirements from our EDMS project. Happy to discuss any aspect of it.

[glpatcern]

Hi @flash7777, thanks for the contribution, I can see the idea is genuine even if the text is produced by Claude.

I do think this makes very much sense. The only issue I can see in terms of implementations is how can a storage provider honor the immutable flag, for the cases (such as how we deploy Reva at CERN) where users have direct access to the storage. But ok this is kind of an implementation detail, the extended permission model could already be used without implementing the immutable RPCs.

[flash7777]

Thanks for the quick feedback!

Good point about the immutable flag and direct storage access. You are right — if users can bypass Reva and access the storage directly (e.g. via EOS FUSE mount), an xattr-based immutable flag alone cannot be enforced.

A few thoughts:

• For decomposedfs (as used by OpenCloud), users never have direct storage access, so xattr-based enforcement works reliably.
• For EOS, the flag could potentially be mapped to EOS ACLs or the existing EOS immutable attribute. But that is indeed an implementation detail per storage driver.
• As you said, the permission fields (delete_container, move_container) are useful independently and can be adopted without implementing the immutable RPCs at all.

Would it make sense to split this into two PRs — one for the permission fields only, and a separate one for immutable? That way the permissions can move forward without being blocked by the immutable discussion.

[flash7777]

One more thought on the direct-access question: regardless of the enforcement layer, the immutable state has to live somewhere. A separate database or metastore would add complexity and synchronization issues. Storing it as an xattr directly on the resource (as Reva already does for locks, ACLs, etc.) seems like the natural fit.

For EOS with FUSE access, the storage driver could map the immutable flag to native EOS attributes (e.g. sys.acl), so FUSE would respect it too. Would it make sense to explore a complementary PR for the EOS driver? We don't have an EOS environment but would be happy to collaborate on the approach.

[glpatcern]

Would it make sense to split this into two PRs

From CS3 Reva side, I'm happy to merge this as is - we'd put stubs for now on the immutable RPCs.

What others think in OpenCloud and ownCloud? @butonic @kobergj

[micbar]

I see that the community is growing and more use cases are evolving. I see no disadvantages with this change, so let’s go for it.

[flash7777]

Pushed a documentation-only update to clarify the immutable semantics based on our EDMS experience. No structural changes to the proto — just refined comments.

Key clarifications:

• File = freeze (irreversible, content fixed)
• Container = protect (structure fixed, reversible by managers)
• Self vs. parent rule: an object is immutable if its own OR its parent's attribute is set

Added docs/proposals/immutable-overview.md as a concise reference spec.

[flash7777]

Added two permission fields for controlling who may set the immutable attribute:

• set_immutable_file (field 23): freeze files — this is irreversible, so it needs to be granted carefully
• set_immutable_container (field 24): protect/unprotect containers — reversible, suitable for space managers

This follows the same pattern as delete/delete_container and move/move_container: separating file and container operations so roles can be configured precisely. A space manager may protect directory structures without being able to permanently freeze files, or vice versa.

[flash7777]

Thanks for the approval @glpatcern! Is there anything else needed before this can be merged? Happy to address any remaining concerns.

[flash7777]

Note: after your approval on May 28, we pushed two additional commits on May 30:

1. docs: clarified immutable semantics (file=freeze vs container=protect, self vs parent rule) — documentation only
2. feat: added set_immutable_file (field 23) and set_immutable_container (field 24) to ResourcePermissions — separates the permission to freeze files (irreversible) from the permission to protect containers (reversible)

Would appreciate a quick look at these additions before merge. The rest is unchanged from what you approved.

[glpatcern]

Thanks @flash7777 and apologies for the late reply. I think it's all ok, the only concern is on the (nowadays AI-generated) doc, as all the rest of the APIs rely on the inline docs to generate https://buf.build/cs3org-buf/cs3apis - but this can be arranged at a later stage. I'll merge the PR.