From 2c2d7f24b167769960ddc87532366301af37eb3e Mon Sep 17 00:00:00 2001
From: Labrys of Knossos <labrys@users.noreply.github.com>
Date: Sat, 31 Dec 2022 18:21:33 -0500
Subject: [PATCH] Add comments.

---
 core/main_db.py     |  2 +-
 core/permissions.py | 30 +++++++++++++++++++++++++++---
 2 files changed, 28 insertions(+), 4 deletions(-)

diff --git a/core/main_db.py b/core/main_db.py
index 2397607f..089ef3a8 100644
--- a/core/main_db.py
+++ b/core/main_db.py
@@ -82,7 +82,7 @@ class DBConnection(object):
                 "  Mode : {1}\n"
                 "  Owner: {2}\n"
                 "  Group: {3}\n"
-                "===========================================".format(path, mode[-3:], owner, group),
+                "===========================================".format(path, mode, owner, group),
             )
         else:
             self.connection.row_factory = Row
diff --git a/core/permissions.py b/core/permissions.py
index 39789672..0b016d30 100644
--- a/core/permissions.py
+++ b/core/permissions.py
@@ -28,36 +28,60 @@ except ImportError:
 
 def mode(path):
     """Get permissions."""
-    return oct(os.stat(path).st_mode & 0o777)
+    stat_result = os.stat(path)  # Get information from path
+    permissions_mask = 0o777  # Set mask for permissions info
+
+    # Get only the permissions part of st_mode as an integer
+    int_mode = stat_result.st_mode & permissions_mask
+    oct_mode = oct(int_mode)  # Convert to octal representation
+
+    return oct_mode[2:]  # Return mode but strip octal prefix
 
 
 def nt_ownership(path):
     """Get the owner and group for a file or directory."""
     def fully_qualified_name(sid):
         """Return a fully qualified account name."""
+        # Look up the account information for the given SID
+        # https://learn.microsoft.com/en-us/windows/win32/api/winbase/nf-winbase-lookupaccountsida
         name, domain, _acct_type = LookupAccountSid(None, sid)
+        # Return account information formatted as DOMAIN\ACCOUNT_NAME
         return '{}\\{}'.format(domain, name)
 
+    # Get the Windows security descriptor for the path
+    # https://learn.microsoft.com/en-us/windows/win32/api/aclapi/nf-aclapi-getnamedsecurityinfoa
     security_descriptor = GetNamedSecurityInfo(
-        os.fspath(path),
-        SE_FILE_OBJECT,
+        path,  # Name of the item to query
+        SE_FILE_OBJECT,  # Type of item to query (file or directory)
+        # Add OWNER and GROUP security information to result
         OWNER_SECURITY_INFORMATION | GROUP_SECURITY_INFORMATION,
     )
+    # Get the Security Identifier for the owner and group from the security descriptor
+    # https://learn.microsoft.com/en-us/windows/win32/api/securitybaseapi/nf-securitybaseapi-getsecuritydescriptorowner
+    # https://learn.microsoft.com/en-us/windows/win32/api/securitybaseapi/nf-securitybaseapi-getsecuritydescriptorgroup
     owner_sid = security_descriptor.GetSecurityDescriptorOwner()
     group_sid = security_descriptor.GetSecurityDescriptorGroup()
+
+    # Get the fully qualified account name (e.g. DOMAIN\ACCOUNT_NAME)
     owner = fully_qualified_name(owner_sid)
     group = fully_qualified_name(group_sid)
+
     return owner, group
 
 
 def posix_ownership(path):
     """Get the owner and group for a file or directory."""
+    # Get path information
     stat_result = os.stat(path)
+
+    # Get account name from path stat result
     owner = pwd.getpwuid(stat_result.st_uid)
     group = grp.getgrgid(stat_result.st_gid)
+
     return owner, group
 
 
+# Select the ownership function appropriate for the platform
 if WINDOWS:
     ownership = nt_ownership
 else: