1 ADR 0002 v1 sharing role permission matrix
Forgejo Actions edited this page 2026-09-25 16:38:07 +00:00

ADR 0002: v1 Sharing Role and Permission Matrix

Status: proposed Date: 2026-05-10

Context

Memories separates media ownership from shared-library visibility. v1 needs a sharing model that is concrete enough for authorization, UI, backup/export, and future migration, but small enough for a family-focused first implementation.

Several permissions are privacy-sensitive and expensive to change later:

  • Whether admins can see private non-contributed media.
  • Whether preview visibility implies original-byte downloads.
  • Whether group members can alter another owner's metadata, people labels, or contribution state.
  • Whether policy changes retroactively expose or hide previously shared metadata.

Options Considered

Option Summary Benefits Costs / Risks
A Broad RBAC with viewer, contributor, editor, moderator, admin, and download roles Flexible for public/non-family sharing Too large for v1; creates unproven authorization surface and UI complexity
B Owner/member only Very small Conflates group operations with ownership; unclear admin privacy boundary
C Small group roles plus owner policy overlays Keeps v1 small while preserving privacy-sensitive owner controls Requires explicit policy checks for downloads, metadata, people, and merges

Decision

Choose Option C: small group roles plus owner policy overlays.

v1 has these roles and authorities:

  • Super Admin: installation/operator role for bootstrap, users, group approval, storage, workers, backup/export, and operational health.
  • Group Admin: sharing-group role for membership and group settings.
  • Group Member: normal trusted family/close-group participant.
  • Media Owner: ownership authority over original assets, contributions, metadata policies, trash/permanent deletion, and people/face approvals.

Sharing group membership roles are group_admin and member. v1 does not add separate viewer or contributor roles.

Super Admin and group admin are not privacy bypass roles. They do not implicitly grant access to private non-contributed media, original-byte downloads, permanent deletion of another owner's originals, another owner's metadata policy changes, or another owner's people/face approvals.

Permission Matrix

Action Media Owner Group Member Group Admin Super Admin
View own private media Yes No No No, unless also owner
View contributed media previews/details Yes Yes, when active group member Yes, when active group member Only when active group member
Download own originals Yes N/A N/A No, unless also owner
Download contributed originals Owner-controlled policy Only if owner allows Only if owner allows Only if owner allows and active member
Contribute own media Yes Yes Yes Yes, for own media
Revoke own contribution Yes Yes Yes Yes, for own media
Revoke another owner's contribution No No No No
Trash/permanently delete another owner's media No No No No
Change own metadata sharing policy Yes Yes, for own media Yes, for own media Yes, for own media
Change another owner's metadata sharing policy No No No No
Revoke own shared metadata snapshots Yes Yes, for own media Yes, for own media Yes, for own media
Create face/person annotations on contributed media Owner policy If owner policy allows If owner policy allows If owner policy allows and active member
Approve face/person annotations on own media Yes No No No
Request person merge Yes Yes, for visible records Yes, for visible records Yes, if active group member
Approve merge involving own person records Yes, by policy Only own records Only own records Only own records
Manage group membership/settings No No Yes Yes, as operator
Request new sharing group Yes Yes Yes Yes
Approve/reject pending sharing group No No No Yes
Remove group member No No Yes Yes
Revoke removed member's group contributions during removal No No Yes, explicit removal option Yes, explicit removal option

Original-byte downloads are controlled separately from preview/detail visibility through an owner policy. The default for family groups is deny until an owner explicitly allows downloads for a group or contribution.

Metadata policy changes apply to future contributions by default. Applying a changed policy to existing contributions, including revoking already-shared metadata snapshots while leaving media visible, is an explicit owner action.

Consequences

  • Media-owner authority remains the central privacy boundary.
  • Admin roles stay operational and do not become hidden super-user access to family media.
  • Preview access and original-byte download access can evolve independently.
  • v1 avoids role explosion while preserving a path to viewer/contributor/public-sharing roles later.
  • Group-owned collaborative albums/events remain deferred unless a later spec promotes them.

Revisit Triggers

Revisit this decision if Memories adds public links, guest users, non-family groups, OIDC/enterprise administration, internet-facing deployments, collaborative group albums/events, or a requirement for admins to perform delegated owner actions.