stash

backend/authentication/api.py

@@ -18,9 +18,8 @@ from hostadmin.models import Domain
 
 router = routers.SimpleRouter()
 
-# Schema for the account-level preferences a client may store on the server (see
-# AccountPreference). Device-level preferences are never sent here - they stay in the
-# browser's local storage since they describe the device, not the account.
+# Schema for account-level preferences a client may store server-side (see AccountPreference);
+# device-level preferences stay in the browser's local storage instead.
 PREFERENCE_DEFINITIONS = [
     {
         'key': 'ui.compact_mode',
@@ -102,9 +101,8 @@ class UserViewSet(viewsets.ModelViewSet):
 @permission_classes([IsAuthenticated])
 @authentication_classes([SignatureAuthenticationLocal])
 def getUserInfo(request):
-    """Get or update the authenticated local user's own account info. Only usable by the
-    account owner on their own home server - see getUserProfile for viewing another (friend)
-    user's public profile."""
+    """Get or update the authenticated local user's own account info; only the account owner may
+    call this on their own home server (see getUserProfile for viewing a friend's public profile)."""
     user = request.user
     if request.method == 'PATCH':
         old_file = user.profile_picture
@@ -147,9 +145,9 @@ def getUserInfo(request):
 @permission_classes([IsAuthenticated])
 @authentication_classes([SignatureAuthentication])
 def getUserProfile(request, handle):
-    """Get another local user's public profile by handle (username@domain), e.g. so a friend
-    can look up someone's avatar. The caller must be a friend of that user (or the user
-    itself, signing with their own known identity rather than their local credentials)."""
+    """Get another local user's public profile by handle, e.g. so a friend can look up an avatar;
+    caller must be a friend of that user (or the user itself, signing with their own known
+    identity rather than local credentials)."""
     try:
         username, domain = split_userhandle_or_throw(handle)
     except ValueError:
@@ -213,11 +211,9 @@ def preference_definitions(request):
 @permission_classes([IsAuthenticated])
 @authentication_classes([SignatureAuthenticationLocal])
 def account_preferences(request):
-    """Get or bulk-upsert the authenticated user's account-level preferences.
-
-    GET returns the current preferences as a {key: value} dict. PUT accepts a {key: value}
-    dict of one or more preferences to set/overwrite; unspecified keys are left untouched.
-    """
+    """Get or bulk-upsert the authenticated user's account-level preferences: GET returns the
+    current preferences as {key: value}; PUT sets/overwrites one or more, leaving unspecified
+    keys untouched."""
     if request.method == 'PUT':
         if not isinstance(request.data, dict):
             return Response({'detail': 'Expected an object of key/value pairs.'}, status=400)

backend/authentication/models.py

@@ -114,11 +114,8 @@ class ToolshedUser(AbstractUser):
 
 
 class AccountPreference(models.Model):
-    """A single account-level (server-synced, cross-device) user preference, stored as a key/value pair.
-
-    Device-level preferences are intentionally *not* stored here - they stay in the browser's
-    local storage since they describe the device, not the account.
-    """
+    """A single account-level (server-synced, cross-device) preference as a key/value pair;
+    device-level preferences are intentionally *not* stored here."""
     user = models.ForeignKey(ToolshedUser, on_delete=models.CASCADE, related_name='preferences')
     key = models.CharField(max_length=255)
     value = models.JSONField()
@@ -165,9 +162,9 @@ class Group(models.Model):
 
 
 class GroupInvite(models.Model):
-    """A pending invite tracked on the group's own home backend, checked when the invitee's
-    accept request arrives (see GroupInviteIncoming for the mirror record on the invitee's own
-    backend, and docs/design-in-progress/groups-mvp.md for the full invite/accept dance)."""
+    """A pending invite tracked on the group's own home backend, checked when the invitee's accept
+    request arrives (mirror: GroupInviteIncoming on the invitee's backend; see
+    docs/design-in-progress/groups-mvp.md)."""
     secret = models.CharField(max_length=255)
     group = models.ForeignKey(Group, on_delete=models.CASCADE, related_name='invites')
     invitee_username = models.CharField(max_length=255)

backend/authentication/signature_auth.py

@@ -81,12 +81,8 @@ def verify_incoming_friend_request(request, raw_request_body):
 
 
 def verify_incoming_group_invite(request, raw_request_body, handle_field, key_field):
-    """Self-certifying verifier for the two legs of the group invite/accept dance that land on a
-    backend which doesn't have the caller cached as a KnownIdentity yet (see
-    docs/design-in-progress/groups-mvp.md): the inviter delivering an invite to the invitee's own
-    backend (handle_field='inviter', key_field='inviter_key'), and the invitee accepting on the
-    group's home backend (handle_field='invitee', key_field='invitee_key'). Mirrors
-    verify_incoming_friend_request exactly, just with configurable field names."""
+    """Self-certifying verifier for the group invite/accept dance. See
+    docs/implementation.md#group-invite-and-accept-self-certifying-verification."""
     try:
         username, domain, signed_data, signature_bytes_hex = verify_request(request, raw_request_body)
     except ValueError:
@@ -143,10 +139,8 @@ def authenticate_request_against_local_users(request, raw_request_body):
 class SignatureAuthentication(authentication.BaseAuthentication):
     def authenticate(self, request):
         identity = authenticate_request_against_known_identities(request, request.body.decode('utf-8'))
-        # Returning a bare None (rather than a (None, None) tuple) tells DRF this
-        # authenticator doesn't apply, so it moves on to the next authenticator in the
-        # authentication_classes list instead of treating the request as authenticated
-        # with an empty user.
+        # Bare None (not a (None, None) tuple) tells DRF to try the next authenticator, instead
+        # of treating the request as authenticated with an empty user.
         if identity is None:
             return None
         return identity, None