From e930bd8919fdc864692b4297cef3474884ed1d8a Mon Sep 17 00:00:00 2001
From: Sergey Motornyuk <sergey.motornyuk@linkdigital.com.au>
Date: Wed, 26 Jun 2024 13:00:18 +0300
Subject: [PATCH] chore: add files_file_scan action

---
 README.md                                     | 135 +++++++++++++-----
 ckanext/files/config.py                       |  11 +-
 ckanext/files/config_declaration.yaml         |  15 +-
 ckanext/files/interfaces.py                   |  55 +++++--
 ckanext/files/logic/action.py                 |  43 +++++-
 ckanext/files/logic/auth.py                   | 118 ++++++++++-----
 ckanext/files/logic/schema.py                 |  11 ++
 ...94bacc491e4_split_and_alter_files_table.py |   6 +-
 ckanext/files/types.py                        |   9 +-
 docs/api.md                                   |  54 +++++--
 10 files changed, 351 insertions(+), 106 deletions(-)

diff --git a/README.md b/README.md
index 7934b18..8dc21ea 100644
--- a/README.md
+++ b/README.md
@@ -556,22 +556,35 @@ assigned as an owner of the file. From now on, the owner can perform other
 operations, such as renaming/displaying/removing with the file.
 
 Apart from chaining auth function, to modify access rules for the file, plugin
-can implement `IFiles.files_is_allowed` method.
+can implement `IFiles.files_file_allows` and `IFiles.files_owner_allows`
+methods.
 
 ```python
-def files_is_allowed(
+def files_file_allows(
     self,
     context: Context,
-    file: File | Multipart | None,
-    operation: types.AuthOperation,
-    next_owner: Any | None,
+    file: File | Multipart,
+    operation: types.FileOperation,
 ) -> bool | None:
     ...
+
+def files_owner_allows(
+    self,
+    context: Context,
+    owner_type: str, owner_id: str,
+    operation: types.OwnerOperation,
+) -> bool | None:
+    ...
+
 ```
 
-This method receives current action context, the file that is accessed, the
-name of operation(`show`, `update`, `delete`, `file_transfer`) and the next
-owner in case of file transfer.
+These methods receive current action context, the tested object details, and
+the name of operation(`show`, `update`, `delete`,
+`file_transfer`). `files_file_allows` checks permission for accessed file. It's
+usually called when user interacts with file directly. `files_owner_allows`
+works with owner described by type and ID. It's usually called when user
+transfer file ownership, perform bulk file operation for owner files, or just
+trying to get the list of files that belongs to owner.
 
 If method returns true/false, operation is allowed/denied. If method returns
 `None`, default logic used to check access.
@@ -580,28 +593,34 @@ As already mentoined, by default, user who owns the file, can access it. But
 what about different owners? What if file owned by other entity, like resource
 or dataset?
 
-Out of the box, nobody can access such files. But there are two config options
-that modify this restriction. `ckanext.files.owner.cascade_access =
-ENTITY_TYPE` gives access to file owned by entity if user already has access to
-entity itself. Use words like `package`, `resource`, `group` instead of
-`ENTITY_TYPE`.
+Out of the box, nobody can access such files. But there are three config
+options that modify this restriction.
+
+`ckanext.files.owner.cascade_access = ENTITY_TYPE ANOTHER_TYPE` gives access to
+file owned by entity if user already has access to entity itself. Use words
+like `package`, `resource`, `group` instead of `ENTITY_TYPE`.
 
 For example: file is owned by *resource*. If cascade access is enabled, whoever
 has access to `resource_show` of the *resource*, can also see the file owned by
 this resource. If user passes `resource_update` for *resource*, he can also
 modify the file owned by this resource, etc.
 
-The second option is `ckanext.files.owner.transfer_as_update`. By default,
-there is no auth function that gives user cascade permission to modify
-ownership of the file. But when transfer-as-update enabled together with
-cascade access, any user who has `resource_update`, can also modify ownership
-of the file owned by *resource*.
-
-Be careful and do not add `user` to
+Important: be careful and do not add `user` to
 `ckanext.files.owner.cascade_access`. User's own files are considered private
 and most likely you don't really need anyone else to be able to see or modify
 these files.
 
+The second option is `ckanext.files.owner.transfer_as_update`.  When
+transfer-as-update enabled, any user who has `<OWNER_TYPE>_update` permission,
+can transfer own files to this `OWNER_TYPE`. Intead of using this option, you
+can define `<OWNER_TYPE>_file_transfer`.
+
+And the third option is `ckanext.files.owner.scan_as_update`.  Just as with
+ownership transfer, it gives user permission to list all files of the owner if
+user can `<OWNER_TYPE>_update` it. Intead of using this option, you
+can define `<OWNER_TYPE>_file_scan`.
+
+
 ### Ownership transfer
 
 File ownership can be transfered. As there can be only one owner of the file,
@@ -611,7 +630,7 @@ To transfer ownership, use `files_transfer_ownership` action and specify `id`
 of the file, `owner_id` and `owner_type` of the new owner.
 
 You can't just transfer ownership to anyone. You either must pass
-`IFiles.files_is_allowed` check for `file_transfer` operation, or pass a
+`IFiles.files_owner_allows` check for `file_transfer` operation, or pass a
 cascade access check for the future owner of the file when cascade access and
 transfer-as-update is enabled.
 
@@ -1618,24 +1637,29 @@ class IFiles(Interface):
         """
         return {}
 
-    def files_is_allowed(
+    def files_file_allows(
         self,
         context: Context,
-        file: File | Multipart | None,
-        operation: types.AuthOperation,
-        next_owner: Any | None,
+        file: File | Multipart,
+        operation: types.FileOperation,
     ) -> bool | None:
         """Decide if user is allowed to perform specified operation on the file.
 
         Return True/False if user allowed/not allowed. Return `None` to rely on
-        other plugins. If every implementation returns `None`, default logic
-        allows only user who owns the file to perform any operation on it. It
-        means, that nobody is allowed to do anything with file owner by
-        resource, dataset, group, etc.
+        other plugins.
+
+        Default implementation relies on cascade_access config option. If owner
+        of file is included into cascade access, user can perform operation on
+        file if he can perform the same operation with file's owner.
+
+        If current owner is not affected by cascade access, user can perform
+        operation on file only if user owns the file.
 
         Example:
-        >>> def files_is_allowed(
-        >>>         self, context, file, operation, next_owner
+        >>> def files_file_allows(
+        >>>         self, context,
+        >>>         file: shared.File | shared.Multipart,
+        >>>         operation: shared.types.FileOperation
         >>> ) -> bool | None:
         >>>     if file.owner_info and file.owner_info.owner_type == "resource":
         >>>         return is_authorized_boolean(
@@ -1646,6 +1670,42 @@ class IFiles(Interface):
         >>>
         >>>     return None
 
+        """
+        return None
+
+    def files_owner_allows(
+        self,
+        context: Context,
+        owner_type: str,
+        owner_id: str,
+        operation: types.OwnerOperation,
+    ) -> bool | None:
+        """Decide if user is allowed to perform specified operation on the owner.
+
+        Return True/False if user allowed/not allowed. Return `None` to rely on
+        other plugins.
+
+        Default implementation relies on cascade_access config option.
+
+        If current owner is not affected by cascade access, user can perform
+        operations only on himself.
+
+
+        Example:
+        >>> def files_owner_allows(
+        >>>         self, context,
+        >>>         owner_type: str, owner_id: str,
+        >>>         operation: shared.types.OwnerOperation
+        >>> ) -> bool | None:
+        >>>     if owner_type == "resource" and operation == "file_transfer":
+        >>>         return is_authorized_boolean(
+        >>>             f"resource_update",
+        >>>             context,
+        >>>             {"id": owner_id}
+        >>>         )
+        >>>
+        >>>     return None
+
         """
         return None
 ```
@@ -1744,12 +1804,17 @@ ckanext.files.authenticated_uploads.storages = default
 # (optional, default: package resource group organization)
 ckanext.files.owner.cascade_access = package resource group organization
 
-# Use `*_update` auth function to check cascade access for ownership
-# transfer. Works with `ckanext.files.owner.cascade_access`, which by itself
-# will check `*_file_transfer` auth function, but switch to `*_update` when
-# this flag is enabled.
+# Use `<OWNER_TYPE>_update` auth function to check access for ownership
+# transfer. When this flag is disabled `<OWNER_TYPE>_file_transfer` auth
+# function is used.
 # (optional, default: true)
 ckanext.files.owner.transfer_as_update = true
+
+# Use `<OWNER_TYPE>_update` auth function to check access when listing all
+# files of the owner. When this flag is disabled `<OWNER_TYPE>_file_scan`
+# auth function is used.
+# (optional, default: true)
+ckanext.files.owner.scan_as_update = true
 ```
 
 ### Storage configuration
diff --git a/ckanext/files/config.py b/ckanext/files/config.py
index 19770e2..e1f3149 100644
--- a/ckanext/files/config.py
+++ b/ckanext/files/config.py
@@ -20,6 +20,7 @@
 DEFAULT_STORAGE = "ckanext.files.default_storage"
 CASCADE_ACCESS = "ckanext.files.owner.cascade_access"
 TRANSFER_AS_UPDATE = "ckanext.files.owner.transfer_as_update"
+SCAN_AS_UPDATE = "ckanext.files.owner.scan_as_update"
 AUTHENTICATED_UPLOADS = "ckanext.files.authenticated_uploads.allow"
 AUTHENTICATED_STORAGES = "ckanext.files.authenticated_uploads.storages"
 USER_IMAGES_STORAGE = "ckanext.files.user_images_storage"
@@ -63,11 +64,19 @@ def authenticated_uploads() -> bool:
 
 
 def transfer_as_update() -> bool:
-    """Use `*_update` auth function to check cascade access for ownership transfer."""
+    """Use `*_update` auth function to check cascade access for ownership
+    transfer."""
 
     return tk.config[TRANSFER_AS_UPDATE]
 
 
+def scan_as_update() -> bool:
+    """Use `*_update` auth function to check cascade access when listing files
+    of the owner."""
+
+    return tk.config[SCAN_AS_UPDATE]
+
+
 def authenticated_storages() -> list[str]:
     """Names of storages that can by used by non-sysadmin users when
     authenticated uploads enabled.
diff --git a/ckanext/files/config_declaration.yaml b/ckanext/files/config_declaration.yaml
index 70cd3d9..452da3f 100644
--- a/ckanext/files/config_declaration.yaml
+++ b/ckanext/files/config_declaration.yaml
@@ -79,10 +79,17 @@ groups:
         type: bool
         default: true
         description: |
-            Use `*_update` auth function to check cascade access for ownership
-            transfer. Works with `ckanext.files.owner.cascade_access`, which by
-            itself will check `*_file_transfer` auth function, but switch to
-            `*_update` when this flag is enabled.
+            Use `<OWNER_TYPE>_update` auth function to check access for
+            ownership transfer. When this flag is disabled
+            `<OWNER_TYPE>_file_transfer` auth function is used.
+
+      - key: ckanext.files.owner.scan_as_update
+        type: bool
+        default: true
+        description: |
+            Use `<OWNER_TYPE>_update` auth function to check access when
+            listing all files of the owner. When this flag is disabled
+            `<OWNER_TYPE>_file_scan` auth function is used.
 
       - key: ckanext.files.storage.<NAME>.<OPTION>
         type: dynamic
diff --git a/ckanext/files/interfaces.py b/ckanext/files/interfaces.py
index 5f8101b..e625a08 100644
--- a/ckanext/files/interfaces.py
+++ b/ckanext/files/interfaces.py
@@ -42,24 +42,29 @@ def files_register_owner_getters(self) -> dict[str, Callable[[str], Any]]:
         """
         return {}
 
-    def files_is_allowed(
+    def files_file_allows(
         self,
         context: Context,
-        file: File | Multipart | None,
-        operation: types.AuthOperation,
-        next_owner: Any | None,
+        file: File | Multipart,
+        operation: types.FileOperation,
     ) -> bool | None:
         """Decide if user is allowed to perform specified operation on the file.
 
         Return True/False if user allowed/not allowed. Return `None` to rely on
-        other plugins. If every implementation returns `None`, default logic
-        allows only user who owns the file to perform any operation on it. It
-        means, that nobody is allowed to do anything with file owner by
-        resource, dataset, group, etc.
+        other plugins.
+
+        Default implementation relies on cascade_access config option. If owner
+        of file is included into cascade access, user can perform operation on
+        file if he can perform the same operation with file's owner.
+
+        If current owner is not affected by cascade access, user can perform
+        operation on file only if user owns the file.
 
         Example:
-        >>> def files_is_allowed(
-        >>>         self, context, file, operation, next_owner
+        >>> def files_file_allows(
+        >>>         self, context,
+        >>>         file: shared.File | shared.Multipart,
+        >>>         operation: shared.types.FileOperation
         >>> ) -> bool | None:
         >>>     if file.owner_info and file.owner_info.owner_type == "resource":
         >>>         return is_authorized_boolean(
@@ -72,3 +77,33 @@ def files_is_allowed(
 
         """
         return None
+
+    def files_owner_allows(
+        self,
+        context: Context,
+        owner_type: str,
+        owner_id: str,
+        operation: types.OwnerOperation,
+    ) -> bool | None:
+        """Decide if user is allowed to perform specified operation on the owner.
+
+        Return True/False if user allowed/not allowed. Return `None` to rely on
+        other plugins.
+
+        Example:
+        >>> def files_owner_allows(
+        >>>         self, context,
+        >>>         owner_type: str, owner_id: str,
+        >>>         operation: shared.types.OwnerOperation
+        >>> ) -> bool | None:
+        >>>     if owner_type == "resource" and operation == "file_transfer":
+        >>>         return is_authorized_boolean(
+        >>>             f"resource_update",
+        >>>             context,
+        >>>             {"id": owner_id}
+        >>>         )
+        >>>
+        >>>     return None
+
+        """
+        return None
diff --git a/ckanext/files/logic/action.py b/ckanext/files/logic/action.py
index 7a7c1c9..68834f2 100644
--- a/ckanext/files/logic/action.py
+++ b/ckanext/files/logic/action.py
@@ -188,11 +188,10 @@ def files_file_search(  # noqa: C901, PLR0912
 
     Returns:
 
-    * `count`: total number of files mathing filters
+    * `count`: total number of files matching filters
     * `results`: array of dictionaries with file details.
 
     """
-
     tk.check_access("files_file_search", context, data_dict)
     sess = context["session"]
 
@@ -715,6 +714,46 @@ def files_multipart_complete(
     return fileobj.dictize(context)
 
 
+@tk.side_effect_free
+@validate(schema.file_scan)
+def files_file_scan(
+    context: Context,
+    data_dict: dict[str, Any],
+) -> dict[str, Any]:
+    """List files of the owner
+
+    This action internally calls files_file_search, but with static values of
+    owner filters. If owner is not specified, files filtered by current
+    user. If owner is specified, user must pass authorization check to see
+    files.
+
+    Params:
+
+    * `owner_id`: ID of the owner
+    * `owner_type`: type of the owner
+
+    The all other parameters are passed as-is to `files_file_search`.
+
+    Returns:
+
+    * `count`: total number of files matching filters
+    * `results`: array of dictionaries with file details.
+
+    """
+    if not data_dict["owner_id"] and data_dict["owner_type"] == "user":
+        user = context.get("auth_user_obj")
+
+        if isinstance(user, model.User) or (user := model.User.get(context["user"])):
+            data_dict["owner_id"] = user.id
+
+
+    tk.check_access("files_file_scan", context, data_dict)
+
+    params = data_dict.pop("__extras", {})
+    params.update(data_dict)
+    return tk.get_action("files_file_search")({"ignore_auth": True}, params)
+
+
 @validate(schema.transfer_ownership)
 def files_transfer_ownership(
     context: Context,
diff --git a/ckanext/files/logic/auth.py b/ckanext/files/logic/auth.py
index 9e59c84..baa3abe 100644
--- a/ckanext/files/logic/auth.py
+++ b/ckanext/files/logic/auth.py
@@ -7,28 +7,64 @@
 from ckan import authz, model
 from ckan.types import AuthResult, Context
 
-from ckanext.files import interfaces, shared, types, utils
+from ckanext.files import interfaces, shared, types
 
 
-def _is_allowed(
+def _owner_allows(
     context: Context,
-    file: shared.File | shared.Multipart | None,
-    operation: types.AuthOperation,
-    next_owner: Any | None = None,
-) -> Any:
+    owner_type: str,
+    owner_id: str,
+    operation: types.OwnerOperation,
+) -> bool:
+    """Decide if user is allowed to perform operation on owner."""
+    for plugin in p.PluginImplementations(interfaces.IFiles):
+        result = plugin.files_owner_allows(context, owner_type, owner_id, operation)
+        if result is not None:
+            return result
+
+    if (operation == "file_transfer" and shared.config.transfer_as_update()) or (
+        operation == "file_scan" and shared.config.scan_as_update()
+    ):
+        func_name = f"{owner_type}_update"
+
+    else:
+        func_name = f"{owner_type}_{operation}"
+
+    try:
+        tk.check_access(
+            func_name,
+            tk.fresh_context(context),
+            {"id": owner_id},
+        )
+
+    except tk.NotAuthorized:
+        return False
+
+    except ValueError:
+        pass
+    return False
+
+
+def _file_allows(
+    context: Context,
+    file: shared.File | shared.Multipart,
+    operation: types.FileOperation,
+) -> bool:
     """Decide if user is allowed to perform operation on file."""
+    for plugin in p.PluginImplementations(interfaces.IFiles):
+        result = plugin.files_file_allows(context, file, operation)
+        if result is not None:
+            return result
+
     info = file.owner_info if file else None
 
     if info and info.owner_type in shared.config.cascade_access():
-        if operation == "file_transfer" and shared.config.transfer_as_update():
-            func_name = f"{info.owner_type}_update"
-        else:
-            func_name = f"{info.owner_type}_{operation}"
+        func_name = f"{info.owner_type}_{operation}"
 
         try:
             tk.check_access(
                 func_name,
-                context,
+                tk.fresh_context(context),
                 {"id": info.owner_id},
             )
 
@@ -37,11 +73,7 @@ def _is_allowed(
 
         except ValueError:
             pass
-
-    for plugin in p.PluginImplementations(interfaces.IFiles):
-        result = plugin.files_is_allowed(context, file, operation, next_owner)
-        if result is not None:
-            return result
+    return False
 
 
 def _get_user(context: Context) -> model.User | None:
@@ -103,20 +135,20 @@ def files_owns_file(context: Context, data_dict: dict[str, Any]) -> AuthResult:
 
 @tk.auth_disallow_anonymous_access
 def files_edit_file(context: Context, data_dict: dict[str, Any]) -> AuthResult:
-    file = _get_file(context, data_dict["id"], data_dict.get("completed", True))
-    result = _is_allowed(context, file, "update")
-    if result is None:
-        return authz.is_authorized("files_owns_file", context, data_dict)
+    result = authz.is_authorized_boolean("files_owns_file", context, data_dict)
+    if not result:
+        file = _get_file(context, data_dict["id"], data_dict.get("completed", True))
+        result = bool(file and _file_allows(context, file, "update"))
 
     return {"success": result, "msg": "Not allowed to edit file"}
 
 
 @tk.auth_disallow_anonymous_access
 def files_read_file(context: Context, data_dict: dict[str, Any]) -> AuthResult:
-    file = _get_file(context, data_dict["id"], data_dict.get("completed", True))
-    result = _is_allowed(context, file, file and file.owner, "show")
-    if result is None:
-        return authz.is_authorized("files_edit_file", context, data_dict)
+    result = authz.is_authorized_boolean("files_owns_file", context, data_dict)
+    if not result:
+        file = _get_file(context, data_dict["id"], data_dict.get("completed", True))
+        result = bool(file and _file_allows(context, file, "show"))
 
     return {"success": result, "msg": "Not allowed to read file"}
 
@@ -160,10 +192,10 @@ def files_file_create(context: Context, data_dict: dict[str, Any]) -> AuthResult
 @tk.auth_disallow_anonymous_access
 def files_file_delete(context: Context, data_dict: dict[str, Any]) -> AuthResult:
     """Only owner can remove files."""
-    file = _get_file(context, data_dict["id"], data_dict.get("completed", True))
-    result = _is_allowed(context, file, "delete")
-    if result is None:
-        return authz.is_authorized("files_edit_file", context, data_dict)
+    result = authz.is_authorized_boolean("files_owns_file", context, data_dict)
+    if not result:
+        file = _get_file(context, data_dict["id"], data_dict.get("completed", True))
+        result = bool(file and _file_allows(context, file, "delete"))
 
     return {"success": result, "msg": "Not allowed to delete file"}
 
@@ -237,15 +269,37 @@ def files_transfer_ownership(context: Context, data_dict: dict[str, Any]) -> Aut
     if file and file.owner_info and file.owner_info.pinned and not data_dict["force"]:
         return {"success": False, "msg": "File is pinned"}
 
-    owner = utils.get_owner(data_dict["owner_type"], data_dict["owner_id"])
-    result = _is_allowed(context, file, "file_transfer", owner)
+    result = authz.is_authorized_boolean("files_manage_files", context, data_dict)
+    if not result:
 
-    if result is None:
-        return authz.is_authorized("files_manage_files", context, data_dict)
+        result = bool(
+            file
+            and _file_allows(context, file, "update")
+            and _owner_allows(
+                context,
+                data_dict["owner_type"],
+                data_dict["owner_id"],
+                "file_transfer",
+            )
+        )
 
     return {"success": result, "msg": "Not allowed to edit file"}
 
 
+def files_file_scan(context: Context, data_dict: dict[str, Any]) -> AuthResult:
+    """Only file owner can list files."""
+    result = authz.is_authorized_boolean("files_manage_files", context, data_dict)
+    if not result:
+        result = _owner_allows(
+            context,
+            data_dict["owner_type"],
+            data_dict["owner_id"],
+            "file_scan",
+        )
+
+    return {"success": result, "msg": "Not allowed to list files"}
+
+
 @tk.auth_disallow_anonymous_access
 def files_resource_upload(context: Context, data_dict: dict[str, Any]) -> AuthResult:
     """Users can upload resources files."""
diff --git a/ckanext/files/logic/schema.py b/ckanext/files/logic/schema.py
index 93f79b2..1184a4e 100644
--- a/ckanext/files/logic/schema.py
+++ b/ckanext/files/logic/schema.py
@@ -152,6 +152,17 @@ def transfer_ownership(
     }
 
 
+@validator_args
+def file_scan(
+    default: ValidatorFactory,
+    unicode_safe: Validator,
+) -> Schema:
+    return {
+        "owner_id": [default(""), unicode_safe],
+        "owner_type": [default("user"), unicode_safe],
+    }
+
+
 @validator_args
 def file_pin(
     boolean_validator: Validator,
diff --git a/ckanext/files/migration/files/versions/008_d94bacc491e4_split_and_alter_files_table.py b/ckanext/files/migration/files/versions/008_d94bacc491e4_split_and_alter_files_table.py
index c547520..4051715 100644
--- a/ckanext/files/migration/files/versions/008_d94bacc491e4_split_and_alter_files_table.py
+++ b/ckanext/files/migration/files/versions/008_d94bacc491e4_split_and_alter_files_table.py
@@ -65,9 +65,9 @@ def upgrade():
 
     for id, name, storage, ctime, data, plugin_data in bind.execute(stmt):
         data["location"] = data.pop("filename")
-        content_type = data.pop("content_type")
-        size = data.pop("size")
-        hash = data.pop("hash")
+        content_type = data.pop("content_type", "application/octet-stream")
+        size = data.pop("size", 0)
+        hash = data.pop("hash", "")
 
         bind.execute(
             sa.insert(multipart_table).values(
diff --git a/ckanext/files/types.py b/ckanext/files/types.py
index fa55c55..567ed97 100644
--- a/ckanext/files/types.py
+++ b/ckanext/files/types.py
@@ -1,7 +1,6 @@
 """Types for the extension.
 
 """
-
 from __future__ import annotations
 
 import tempfile
@@ -20,11 +19,12 @@
     ValidatorFactory,
 )
 
-AuthOperation = Literal["show", "update", "delete", "file_transfer"]
+FileOperation = Literal["show", "update", "delete"]
+OwnerOperation = Literal["show", "update", "delete", "file_transfer", "file_scan"]
 
 Uploadable = Union[
     FileStorage,
-    tempfile.SpooledTemporaryFile[Any],
+    "tempfile.SpooledTemporaryFile[Any]",
     TextIOWrapper,
     bytes,
     bytearray,
@@ -45,7 +45,8 @@ def __iter__(self) -> Iterator[bytes]: ...
     "FlattenKey",
     "FlattenErrorDict",
     "FlattenDataDict",
-    "AuthOperation",
     "Declaration",
+    "FileOperation",
+    "OwnerOperation",
     "Key",
 ]
diff --git a/docs/api.md b/docs/api.md
index 9c25936..afd3037 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -1,4 +1,4 @@
-## files_file_create
+## `files_file_create(context: 'Context', data_dict: 'dict[str, Any]') -> 'dict[str, Any]'`
 
 Create a new file.
 
@@ -38,7 +38,7 @@ Returns:
 dictionary with file details.
 
 
-## files_file_delete
+## `files_file_delete(context: 'Context', data_dict: 'dict[str, Any]') -> 'dict[str, Any]'`
 
 Remove file from storage.
 
@@ -65,7 +65,7 @@ Returns:
 dictionary with details of the removed file.
 
 
-## files_file_pin
+## `files_file_pin(context: 'Context', data_dict: 'dict[str, Any]') -> 'dict[str, Any]'`
 
 Pin file to the current owner.
 
@@ -83,7 +83,7 @@ Returns:
 dictionary with details of updated file
 
 
-## files_file_rename
+## `files_file_rename(context: 'Context', data_dict: 'dict[str, Any]') -> 'dict[str, Any]'`
 
 Rename the file.
 
@@ -107,7 +107,29 @@ Returns:
 dictionary with file details
 
 
-## files_file_search
+## `files_file_scan(context: 'Context', data_dict: 'dict[str, Any]') -> 'dict[str, Any]'`
+
+List files of the owner
+
+This action internally calls files_file_search, but with static values of
+owner filters. If owner is not specified, files filtered by current
+user. If owner is specified, user must pass authorization check to see
+files.
+
+Params:
+
+* `owner_id`: ID of the owner
+* `owner_type`: type of the owner
+
+The all other parameters are passed as-is to `files_file_search`.
+
+Returns:
+
+* `count`: total number of files matching filters
+* `results`: array of dictionaries with file details.
+
+
+## `files_file_search(context: 'Context', data_dict: 'dict[str, Any]') -> 'dict[str, Any]'`
 
 Search files.
 
@@ -168,16 +190,16 @@ Params:
 
 Returns:
 
-* `count`: total number of files mathing filters
+* `count`: total number of files matching filters
 * `results`: array of dictionaries with file details.
 
 
-## files_file_search_by_user
+## `files_file_search_by_user(context: 'Context', data_dict: 'dict[str, Any]') -> 'dict[str, Any]'`
 
 Internal action. Do not use it.
 
 
-## files_file_show
+## `files_file_show(context: 'Context', data_dict: 'dict[str, Any]') -> 'dict[str, Any]'`
 
 Show file details.
 
@@ -198,7 +220,7 @@ Returns:
 dictionary with file details
 
 
-## files_file_unpin
+## `files_file_unpin(context: 'Context', data_dict: 'dict[str, Any]') -> 'dict[str, Any]'`
 
 Pin file to the current owner.
 
@@ -216,7 +238,7 @@ Returns:
 dictionary with details of updated file
 
 
-## files_multipart_complete
+## `files_multipart_complete(context: 'Context', data_dict: 'dict[str, Any]') -> 'dict[str, Any]'`
 
 Finalize multipart upload and transform it into completed file.
 
@@ -239,7 +261,7 @@ Returns:
 dictionary with details of the created file
 
 
-## files_multipart_refresh
+## `files_multipart_refresh(context: 'Context', data_dict: 'dict[str, Any]') -> 'dict[str, Any]'`
 
 Refresh details of incomplete upload.
 
@@ -257,7 +279,7 @@ Returns:
 dictionary with details of the updated upload
 
 
-## files_multipart_start
+## `files_multipart_start(context: 'Context', data_dict: 'dict[str, Any]') -> 'dict[str, Any]'`
 
 Initialize multipart(resumable,continuous,signed,etc) upload.
 
@@ -284,7 +306,7 @@ Returns:
 dictionary with details of initiated upload. Depends on used storage
 
 
-## files_multipart_update
+## `files_multipart_update(context: 'Context', data_dict: 'dict[str, Any]') -> 'dict[str, Any]'`
 
 Update incomplete upload.
 
@@ -302,7 +324,7 @@ Returns:
 dictionary with details of the updated upload
 
 
-## files_resource_upload
+## `files_resource_upload(context: 'Context', data_dict: 'dict[str, Any]')`
 
 Create a new file inside resource storage.
 
@@ -322,7 +344,7 @@ Returns:
 dictionary with file details.
 
 
-## files_transfer_ownership
+## `files_transfer_ownership(context: 'Context', data_dict: 'dict[str, Any]') -> 'dict[str, Any]'`
 
 Transfer file ownership.
 
@@ -341,3 +363,5 @@ Params:
 Returns:
 
 dictionary with details of updated file
+
+