feat: Overhaul the Property Scopes and Profile chapter

admin_manual/configuration_user/profile_configuration.rst

@@ -1,73 +1,237 @@
 .. _profile:
 
-=====================
-Profile configuration
-=====================
+========
+Profiles
+========
 
-The user profile presents the information of a user and is enabled by default
-for all users. Users may individually enable or disable their profile in their
-Personal info settings under the Personal settings section.
+The user profile displays information about an account.
+Profiles are enabled by default.
 
-As an administrator you may change the default for new users and may also
-disable profile globally to remove all profile functionality.
+Users can enable or disable their own profile in **Personal settings** under
+**Personal info**.
 
-Profile properties are also written into the :ref:`system address book<system-address-book>`.
+As an administrator, you can:
 
-.. note:: If not disabled, the profile is publicly visible.
-  The visibility of the individual profile attributes can be either controlled
-  by the assigned visibility scopes (e.g. "Private" will disable public access),
-  or by the user defined profile visibility.
+- set the default profile state for new users, and
+- disable profiles globally.
+
+Profile data can also be used by other features (for example the
+:ref:`system address book<system-address-book>`), but what is exposed depends
+on privacy controls.
+
+.. note::
+   Profile visibility is layered.
+
+   - **Profile enablement** determines if the profile feature is active at all.
+   - **Profile field visibility settings** control whether a field is shown.
+   - **Account property scopes** (for example ``private``, ``local``, ``federated``,
+     ``published``) define the intended audience for each property.
+   - **Discovery restrictions** (for example sharing/autocomplete enumeration rules)
+     can further reduce what other accounts can find or see.
+
+   In short: effective visibility is the most restrictive result of all applicable controls.
 
 Configuration
 -------------
 
-To enable or disable profile by default for new users switch the toggle in
-Basic settings under the Administration settings section.
+Set the profile default for new users
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In **Administration settings** -> **Basic settings**, use the profile default toggle.
 
 .. figure:: ../images/profile_default_setting.png
 
-You may also run the ``occ`` command below instead to change the default to ``false``:
+You can also set this via ``occ``:
 
 ::
 
   occ config:app:set settings profile_enabled_by_default --value="0"
 
-Please refer to :doc:`../occ_command` for all available
-``occ`` commands.
+Use ``--value="1"`` to enable it by default again.
 
-To disable profile globally add the following line to your ``config.php``
+See :doc:`../occ_command` for more ``occ`` usage details.
+
+Disable profiles globally
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To disable profile functionality for all users, add this to ``config.php``:
 
 ::
 
   'profile.enabled' => false,
 
-Please refer to :doc:`../configuration_server/config_sample_php_parameters` for
-all available ``config.php`` options.
-
 .. _profile-property-scopes:
 
-Property scopes
----------------
+Property visibility scopes
+---------------------------
 
-User properties (Full name, Address, Website, Role, …) have specific visibility scopes (Private, Local, Federated, Published).
+User properties (Display name, Address, Website, Role, etc.) have visibility scopes:
+Private, Local, Federated, Published.
 
-The visibility scopes are explained below:
+These scopes are evaluated per attribute. A profile being reachable does not imply
+that all its attributes are visible.
+
+The visibility scopes are:
 
 :Private:
-  Contact details visible locally only
+
+  The most restrictive level. Data is hidden from public profiles, federation, and
+  public lookup. On the local server, it is only shown in specific features and
+  typically only to authenticated users who have a recognized relationship with the
+  account owner (for example, as a known contact).
+
 :Local:
-  Contact details visible locally and through public link access on local instance
+  Contact details visible on the local instance and in some public contexts where
+  profile/account attributes are required (for example owner/uploader metadata).
+  Not shared to federated servers and not published to the public lookup server.
+
 :Federated:
-  Contact details visible locally, through public link access and on trusted federated servers.
+  Contact details visible on the local instance, in relevant public contexts,
+  and on trusted federated servers.
+
 :Published:
-  Contact details visible locally, through public link access, on trusted federated servers and published to the public lookup server.
+  Contact details visible on the local instance, in relevant public contexts,
+  on trusted federated servers, and published to the public lookup server.
+
+.. note::
+   **Public lookup server**: a public directory used to find users across Nextcloud instances.
+   Only profile fields marked Published may be exposed there.
+
+.. important::
+   A reachable profile does not mean all attributes are public. Each attribute is
+   filtered by its own scope, and effective visibility can also depend on the
+   consuming feature.
+
+.. important::
+   On profile surfaces, the effective visibility is the more restrictive of
+   profile-visibility settings and property scope.
+
+Scope visibility matrix
+^^^^^^^^^^^^^^^^^^^^^^^
+
++------------+-------------------+-------------------------------------------------------+--------------------------------------+---------------------+----------------------+
+| Scope      | User themself [1] | Other users on same local instance                    | Public contexts (feature-dependent)  | Trusted federation  | Public lookup server |
++============+===================+=======================================================+======================================+=====================+======================+
+| Private    | Yes               | Limited: authenticated + known-user relation required | No                                   | No                  | No                   |
++------------+-------------------+-------------------------------------------------------+--------------------------------------+---------------------+----------------------+
+| Local      | Yes               | Yes                                                   | Yes (where applicable) [2]           | No                  | No                   |
++------------+-------------------+-------------------------------------------------------+--------------------------------------+---------------------+----------------------+
+| Federated  | Yes               | Yes                                                   | Yes (where applicable) [2]           | Yes                 | No                   |
++------------+-------------------+-------------------------------------------------------+--------------------------------------+---------------------+----------------------+
+| Published  | Yes               | Yes                                                   | Yes (where applicable) [2]           | Yes                 | Yes                  |
++------------+-------------------+-------------------------------------------------------+--------------------------------------+---------------------+----------------------+
+
+Notes:
+
+1. Scope primarily governs exposure to others; owner access follows account/endpoint behavior.
+2. Public-context visibility depends on feature path; scope alone does not guarantee display.
+
+Known-user rule for ``Private`` scope
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+For ``Private`` properties, Nextcloud may allow visibility on specific local feature
+paths only when the requester is considered a *known user* of the target user.
+
+In practical terms, this relation is derived by server-side known-contact logic and is
+directional (e.g., Alice might be in Bob's contacts, but Bob isn't necessarily in
+Alice's). Users are always known to themselves.
+
+What local users can see
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+A common question is what one user can see about another user on the same instance.
+
+In general, profile visibility is controlled by each property's scope, but the
+exact UI/API surface depends on the consuming feature (for example profile page,
+share dialogs, search, mentions, Contacts, and other integrations).
+
+For local users on the same instance:
+
+- ``Private``: not generally visible to all local users; visibility is restricted
+  on applicable paths to authenticated users that satisfy the known-user relation
+  and other feature constraints.
+- ``Local``: visible on the local instance.
+- ``Federated``: visible on the local instance (and also shared with trusted federated servers).
+- ``Published``: visible on the local instance (and also federated + public lookup).
+
+.. note::
+   System address book exposure is scope-aware and context-aware:
+   private/empty-scope properties are excluded from generated cards, and
+   federated reads strip local-scoped properties.
+
+How to verify scope behavior
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Because effective visibility can vary by feature path, administrators should verify
+scope behavior in their own deployment.
+
+Recommended test procedure:
+
+1. Create test users:
+
+   - ``alice`` (target profile owner)
+   - ``bob`` (authenticated local user)
+   - ``charlie`` (second local user for control)
+
+2. As ``alice``, set distinct test values for profile fields and assign different
+   scopes (Private, Local, Federated, Published).
+3. Verify as ``alice``:
+
+   - Confirm owner-visible values as expected.
+
+4. Verify as ``bob`` (authenticated local user):
+
+   - Check the feature paths used in your instance (for example profile page,
+     user card, share dialog, search, mentions, Contacts integrations).
+   - Confirm ``Local/Federated/Published`` fields are visible where expected.
+   - Confirm ``Private`` fields are visible only on paths that satisfy the known-user
+     relation and other feature constraints.
 
-The default values for each property for each new user is listed below, but you should consult the declaration of the ``DEFAULT_SCOPES`` constant in the ``OC\Accounts\AccountManager`` class (`see the code <https://github.com/nextcloud/server/blob/master/lib/private/Accounts/AccountManager.php>`_) to make sure these are up-to-date.
+5. Verify as unauthenticated user (private browser session):
+
+   - Confirm only public-appropriate fields are visible.
+
+6. Verify federation/publication behavior (if enabled):
+
+   - From a trusted federated server, confirm Federated/Published behavior.
+   - Confirm only Published fields are exposed to the public lookup server.
+
+7. Re-test with a newly created user after changing
+   ``account_manager.default_property_scope``:
+
+   - Confirm new defaults apply only to newly initialized accounts.
+   - Confirm existing users retain stored scopes unless explicitly changed.
+
+Scope defaults and precedence
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Visibility is determined per property using this order:
+
+1. **Server defaults** from ``OC\Accounts\AccountManager::DEFAULT_SCOPES``.
+2. **Administrator default override** via ``account_manager.default_property_scope``.
+3. **User-set value** in personal/profile settings (subject to server-side constraints).
+
+Practical implications:
+
+- Admin overrides in ``account_manager.default_property_scope`` are applied at account
+  initialization and therefore affect **new users**.
+- Existing users keep already stored scopes unless changed explicitly.
+- ``PROPERTY_DISPLAYNAME`` and ``PROPERTY_EMAIL`` cannot be ``Private``; server-side
+  validation/enforcement requires at least ``Local``.
+
+Default scope values (reference)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Default values are defined in server code and may change over time. The authoritative
+source is the ``DEFAULT_SCOPES`` constant in ``OC\Accounts\AccountManager``:
+`latest source <https://github.com/nextcloud/server/blob/master/lib/private/Accounts/AccountManager.php>`_.
+
+Example defaults (verify against your deployed version):
 
 +--------------+--------------------------+
 | Property     | Default visibility scope |
 +==============+==========================+
-| Full name    | Federated                |
+| Display name | Federated                |
 +--------------+--------------------------+
 | Address      | Local                    |
 +--------------+--------------------------+
@@ -81,6 +245,10 @@ The default values for each property for each new user is listed below, but you
 +--------------+--------------------------+
 | Twitter      | Local                    |
 +--------------+--------------------------+
+| Bluesky      | Local                    |
++--------------+--------------------------+
+| Fediverse    | Local                    |
++--------------+--------------------------+
 | Organisation | Local                    |
 +--------------+--------------------------+
 | Role         | Local                    |
@@ -89,14 +257,93 @@ The default values for each property for each new user is listed below, but you
 +--------------+--------------------------+
 | Biography    | Local                    |
 +--------------+--------------------------+
+| Birthdate    | Local                    |
++--------------+--------------------------+
+| Pronouns     | Federated                |
++--------------+--------------------------+
 
-If you'd like to override the value for one or several default visibility scopes, use the ``account_manager.default_property_scope`` ``config.php`` configuration key, which defaults to an empty array:
+Override default scopes in ``config.php``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To override one or several default visibility scopes for *new users*, use
+``account_manager.default_property_scope`` (default: empty array):
 
 .. code-block:: php
 
   'account_manager.default_property_scope' => [
     \OCP\Accounts\IAccountManager::PROPERTY_PHONE => \OCP\Accounts\IAccountManager::SCOPE_PRIVATE,
-    \OCP\Accounts\IAccountManager::PROPERTY_ROLE => \OCP\Accounts\IAccountManager::SCOPE_FEDERATED
+    \OCP\Accounts\IAccountManager::PROPERTY_ROLE => \OCP\Accounts\IAccountManager::SCOPE_FEDERATED,
   ]
 
-In the above example, the phone and role properties are respectively overwritten to the private and federated scopes. Note that these changes will only apply to *new* users, not existing ones.
+In the above example, phone and role are overwritten to ``Private`` and
+``Federated`` respectively.
+
+.. note::
+   Use ``\OCP\Accounts\IAccountManager`` constants for both property keys and scope values.
+
+FAQ: How to lock profile visibility down
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If your goal is maximum privacy:
+
+1. Disable profiles globally (strictest option):
+
+   .. code-block:: php
+
+     'profile.enabled' => false,
+
+   Effect:
+
+   - Profile functionality is removed.
+   - Profile-based discoverability/usability features are reduced accordingly.
+
+2. If profiles must remain enabled, set restrictive defaults for new users:
+
+   .. code-block:: php
+
+     'account_manager.default_property_scope' => [
+       \OCP\Accounts\IAccountManager::PROPERTY_ADDRESS => \OCP\Accounts\IAccountManager::SCOPE_PRIVATE,
+       \OCP\Accounts\IAccountManager::PROPERTY_PHONE => \OCP\Accounts\IAccountManager::SCOPE_PRIVATE,
+       \OCP\Accounts\IAccountManager::PROPERTY_WEBSITE => \OCP\Accounts\IAccountManager::SCOPE_PRIVATE,
+       \OCP\Accounts\IAccountManager::PROPERTY_TWITTER => \OCP\Accounts\IAccountManager::SCOPE_PRIVATE,
+       \OCP\Accounts\IAccountManager::PROPERTY_BLUESKY => \OCP\Accounts\IAccountManager::SCOPE_PRIVATE,
+       \OCP\Accounts\IAccountManager::PROPERTY_FEDIVERSE => \OCP\Accounts\IAccountManager::SCOPE_PRIVATE,
+       \OCP\Accounts\IAccountManager::PROPERTY_ORGANISATION => \OCP\Accounts\IAccountManager::SCOPE_PRIVATE,
+       \OCP\Accounts\IAccountManager::PROPERTY_ROLE => \OCP\Accounts\IAccountManager::SCOPE_PRIVATE,
+       \OCP\Accounts\IAccountManager::PROPERTY_HEADLINE => \OCP\Accounts\IAccountManager::SCOPE_PRIVATE,
+       \OCP\Accounts\IAccountManager::PROPERTY_BIOGRAPHY => \OCP\Accounts\IAccountManager::SCOPE_PRIVATE,
+       \OCP\Accounts\IAccountManager::PROPERTY_BIRTHDATE => \OCP\Accounts\IAccountManager::SCOPE_PRIVATE,
+       \OCP\Accounts\IAccountManager::PROPERTY_PRONOUNS => \OCP\Accounts\IAccountManager::SCOPE_PRIVATE,
+       \OCP\Accounts\IAccountManager::PROPERTY_AVATAR => \OCP\Accounts\IAccountManager::SCOPE_PRIVATE,
+     ]
+
+   Notes:
+
+   - ``PROPERTY_DISPLAYNAME`` and ``PROPERTY_EMAIL`` cannot be set to ``Private``; server-side enforcement requires at least ``Local``.
+   - Defaults apply to **new users**. Existing users keep stored scopes unless changed.
+
+What becomes limited when you lock it down?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+With more restrictive scopes (especially ``Private``), expect reduced visibility in:
+
+- User discovery/search/user cards
+- Share dialogs and mention/autocomplete context
+- Public/share-related contexts where account metadata may be shown
+- Federated visibility of profile attributes
+- Public lookup publication (only ``Published`` appears there)
+
+In short: tighter privacy reduces profile-based convenience and discoverability.
+
+.. TODO/Future additions
+   - Sharing settings + Mentions + Property Scope interactions (i.e. auto-completion, group/user-to-group/user sharing)
+   - Since default visibility scope changes only apply to new users, perhaps we can cover whether there's a migration path for existing users?
+   - better integrate (cross-link? separate out?) with chapters covering sharing and federation
+   - unify with User Manual
+   - Dev Manual coverage 
+   - better "known user context" description
+   - better "public contexts" description
+   - better "varies by feature/UI/API/app" description
+   - more definite statements; more direct statements
+   - simplify simplify simplify
+