chore: docs, fix type annotation

Author: rexzhang

.markdownlint.json

@@ -0,0 +1,4 @@
+{
+  "MD013": false,
+  "MD024": false
+}

asgi_webdav/auth.py

@@ -167,7 +167,7 @@ async def check_ldap_password_v1(
 
     async def check_ldap_password_v2(
         self, username: str, password: str
-    ) -> (bool, str | None):
+    ) -> tuple[bool, str | None]:
         """
         <ldap>#2#{ldap-uri}#{ldap-params}#{ldap-user}
         <ldap>#2#ldaps:/your.domain.com#cert_policy=try#uid={username},cn=users,cn=accounts,dc=domain,dc=tld
@@ -581,6 +581,8 @@ async def pick_out_user(self, request: DAVRequest) -> tuple[DAVUser | None, str]
                 # The user does not exist in the data file, but may be in the LDAP fallback.
                 # Copy the data to avoid overwriting the template for future sessions.
                 fallback = self.user_mapping.get("*ldap")
+                # All future third-party authentication backends will begin with "*"
+                # - use "*ldap" for ldap.
                 if fallback is None:
                     # A fallback is not configured.
                     return None, "no permission"

docs/changelog.en.md

@@ -1,7 +1,6 @@
 # Changelog
 
-
-## 1.4.2 - 20250424
+## x.y.z - ?
 
 - Allow authenticating any user from LDAP server, thanks [PIC](https://www.pic.es)
 

docs/guide/protect-your-password-in-the-config.en.md

@@ -2,29 +2,29 @@
 
 ```json
 {
-    "account_mapping": [
-        {"username": "user-raw", "password": "password", "permissions": ["+"]},
-        {
-            "username": "user-hashlib",
-            "password": "<hashlib>:sha256:salt:291e247d155354e48fec2b579637782446821935fc96a5a08a0b7885179c408b",
-            "permissions": ["+^/$"]
-        },
-        {
-            "username": "user-digest",  
-            "password": "<digest>:ASGI-WebDAV:c1d34f1e0f457c4de05b7468d5165567",
-            "permissions": ["+^/$"]
-        },
-        {
-            "username": "user-ldap",
-            "password": "<ldap>#1#ldaps://your.ldap.server.com#SIMPLE#uid=user-ldap,cn=users,dc=your.ldap.server.com",
-            "permissions": ["+^/$"]
-        },
-        {
-            "username": "*",
-            "password": "<ldap>#2#ldaps://your.ldap.server.com#cert_policy=try#uid={username},cn=users,dc=your.ldap.server.com",
-            "permissions": ["+^/$"]
-        }
-    ]
+  "account_mapping": [
+    { "username": "user-raw", "password": "password", "permissions": ["+"] },
+    {
+      "username": "user-hashlib",
+      "password": "<hashlib>:sha256:salt:291e247d155354e48fec2b579637782446821935fc96a5a08a0b7885179c408b",
+      "permissions": ["+^/$"]
+    },
+    {
+      "username": "user-digest",
+      "password": "<digest>:ASGI-WebDAV:c1d34f1e0f457c4de05b7468d5165567",
+      "permissions": ["+^/$"]
+    },
+    {
+      "username": "user-ldap",
+      "password": "<ldap>#1#ldaps://your.ldap.server.com#SIMPLE#uid=user-ldap,cn=users,dc=your.ldap.server.com",
+      "permissions": ["+^/$"]
+    },
+    {
+      "username": "*ldap",
+      "password": "<ldap>#2#ldaps://your.ldap.server.com#cert_policy=try#uid={username},cn=users,dc=your.ldap.server.com",
+      "permissions": ["+^/$"]
+    }
+  ]
 }
 ```
 
@@ -37,6 +37,7 @@ user `user-raw`'s password is real password
 `password`'s format is `"<hashlib>:{algorithm}:{salt}:{hashed-password}"`
 
 ### {algorithm}
+
 A list of supported `{algorithms}` can be found at [Python's docs](https://docs.python.org/3.10/library/hashlib.html)
 
 The commonly used algorithms:
@@ -48,9 +49,11 @@ The commonly used algorithms:
 - blake2s (optimized for 8- to 32-bit platforms)
 
 ### {salt}
+
 `{salt}` can be any string
 
 ### {hashed-password}
+
 `{hashed-password}`'s format is `ALGORITHM(bytes("{salt}:{password}")).hexdigest()`
 
 example:
@@ -59,23 +62,26 @@ example:
 - {salt}: `salt`
 - {password}: `password`
 
-```
+```text
 >>> import hashlib
 >>> hashlib.new("sha256", "{}:{}".format("salt", "password").encode("utf-8")).hexdigest()
 '291e247d155354e48fec2b579637782446821935fc96a5a08a0b7885179c408b'
 ```
 
 ### Ref
 
-- https://en.wikipedia.org/wiki/Comparison_of_cryptographic_hash_functions
+- <https://en.wikipedia.org/wiki/Comparison_of_cryptographic_hash_functions>
 
 ## HTTP Digest Mode
+
 `password`'s format is `<digest>:{realm}:{HA1}`
 
 ### {realm}
+
 `ASGI-WebDAV`
 
 ### {HA1}
+
 `{HA1}`'s format is `md5(bytes("{username}:{realm}:{password}")).hexdigest()`
 
 example:
@@ -84,26 +90,30 @@ example:
 - {realm}: `ASGI-WebDAV`
 - {password}: `password`
 
-```
+```text
 >>> import hashlib
 >>> hashlib.new("md5", "{}:{}:{}".format("user-digest", "ASGI-WebDAV", "password").encode("utf-8")).hexdigest()
 'c1d34f1e0f457c4de05b7468d5165567'
 ```
 
 ### Ref
+
 - [RFC2617](https://datatracker.ietf.org/doc/html/rfc2617)
 
-## LDAP Mode (experimental)
-`password`'s format is `"<ldap>#1#{ldap-uri}#{mechanism}#{ldap-user}"`
+## LDAP(v1) (experimental)
+
+### password format
+
+```text
+"<ldap>#1#{ldap-uri}#{mechanism}#{ldap-user}"
+```
 
 ### {ldap-uri}
 
 Example:
 
 `ldap://your.ldap.server.com` `ldaps://your.tls.ldap.server.com`
 
-#### Ref
-
 - [Official Website](https://ldap.com/ldap-urls/)
 - [RFC4516](https://docs.ldap.com/specs/rfc4516.txt)
 
@@ -119,9 +129,22 @@ Example:
 
 `uid=you-name,cn=users,dc=ldap,dc=server,dc=com`
 
-## LDAP fallback
-Use `"*"` as `username` to use it as fallback for any user not explicitly set in the configuration file.
-`password`'s format is `"<ldap_users>#ldaps://{ldap-uri}#{params}#{user-dn-pattern}"`.
+## LDAP(v2)
+
+### username
+
+Use `"*"` as `username`
+
+### password format
+
+```text
+"<ldap_users>#ldaps://{ldap-uri}#{params}#{user-dn-pattern}"
+```
+
+### permissions
+
+WARNING:
+`permissions` will be automatically applied to all ldap accounts.
 
 ### {ldap-uri}
 
@@ -140,8 +163,8 @@ This is a query string specifying additional optional settings. Only one is supp
 
 `cert_policy` indicates the policy about server verification. The allowed values are:
 
-* `try` or `demand`: The server cert will be verified, and if it fais, an error will be raised. This is the default.
-* `never` or `allow`: The server cert will be used without any verification.
+- `try` or `demand`: The server cert will be verified, and if it fais, an error will be raised. This is the default.
+- `never` or `allow`: The server cert will be used without any verification.
 
 Example:
 
@@ -151,7 +174,6 @@ Example:
 
 - [RFC1866](https://datatracker.ietf.org/doc/html/rfc1866)
 
-
 ### {user-dn-pattern}
 
 Specify the user DN pattern, with a `username` substitution field. Example:
@@ -161,8 +183,9 @@ Specify the user DN pattern, with a `username` substitution field. Example:
 ## Compatibility
 
 |                  | HTTP Basic auth | HTTP Digest auth |
-|------------------|-----------------|------------------|
+| ---------------- | --------------- | ---------------- |
 | Raw Mode         | Y               | Y                |
 | hashlib Mode     | Y               | N                |
 | HTTP Digest Mode | Y               | Y                |
-| LDAP Mode        | Y               | N                |
+| LDAP(v1)         | Y               | N                |
+| LDAP(v2)         | Y               | N                |