Add listing of configuration keys in 'simple' mode (#240)

Author: jdevera

README.md

@@ -413,6 +413,7 @@ The use of environment variables allow you to provide over-rides to default sett
 | `APPRISE_STATELESS_URLS` | For a non-persistent solution, you can take advantage of this global variable. Use this to define a default set of Apprise URLs to notify when using API calls to `/notify`.  If no `{KEY}` is defined when calling `/notify` then the URLs defined here are used instead. By default, nothing is defined for this variable.
 | `APPRISE_STATEFUL_MODE` | This can be set to the following possible modes:<br/>📌 **hash**: This is also the default.  It stores the server configuration in a hash formatted that can be easily indexed and compressed.<br/>📌 **simple**: Configuration is written straight to disk using the `{KEY}.cfg` (if `TEXT` based) and `{KEY}.yml` (if `YAML` based).<br/>📌 **disabled**: Straight up deny any read/write queries to the servers stateful store.  Effectively turn off the Apprise Stateful feature completely.
 | `APPRISE_CONFIG_LOCK` | Locks down your API hosting so that you can no longer delete/update/access stateful information. Your configuration is still referenced when stateful calls are made to `/notify`.  The idea of this switch is to allow someone to set their (Apprise) configuration up and then as an added security tactic, they may choose to lock their configuration down (in a read-only state). Those who use the Apprise CLI tool may still do it, however the `--config` (`-c`) switch will not successfully reference this access point anymore. You can however use the `apprise://` plugin without any problem ([see here for more details](https://github.com/caronc/apprise/wiki/Notify_apprise_api)). This defaults to `no` and can however be set to `yes` by simply defining the global variable as such.
+| `APPRISE_ADMIN` | Enables admin mode. This removes the distinction between users and admins and allows listing stored configuration keys (when `STATEFUL_MODE` is set to `simple`). This defaults to `no` and can be set to `yes`.
 | `APPRISE_DENY_SERVICES` | A comma separated set of entries identifying what plugins to deny access to. You only need to identify one schema entry associated with a plugin to in turn disable all of it.  Hence, if you wanted to disable the `glib` plugin, you do not need to additionally include `qt` as well since it's included as part of the (`dbus`) package; consequently specifying `qt` would in turn disable the `glib` module as well (another way to accomplish the same task).  To exclude/disable more the one upstream service, simply specify additional entries separated by a `,` (comma) or ` ` (space). The `APPRISE_DENY_SERVICES` entries are ignored if the `APPRISE_ALLOW_SERVICES` is identified. By default, this is initialized to `windows, dbus, gnome, macosx, syslog` (blocking local actions from being issued inside of the docker container)
 | `APPRISE_ALLOW_SERVICES` | A comma separated set of entries identifying what plugins to allow access to. You may only use alpha-numeric characters as is the restriction of Apprise Schemas (schema://) anyway.  To exclusively include more the one upstream service, simply specify additional entries separated by a `,` (comma) or ` ` (space). The `APPRISE_DENY_SERVICES` entries are ignored if the `APPRISE_ALLOW_SERVICES` is identified.
 | `APPRISE_ATTACH_ALLOW_URLS` | A comma separated set of entries identifying the HTTP Attach URLs the Apprise API shall always accept.  Use wildcards such as `*` and `?` to help construct the URL/Hosts you identify. Use a space and/or a comma to identify more then one entry. By default this is set to `*` (Accept all provided URLs).

apprise_api/api/context_processors.py

@@ -42,6 +42,13 @@ def config_lock(request):
     return {'CONFIG_LOCK': settings.APPRISE_CONFIG_LOCK}
 
 
+def admin_enabled(request):
+    """
+    Returns whether we allow the config list to be displayed
+    """
+    return {'APPRISE_ADMIN': settings.APPRISE_ADMIN}
+
+
 def apprise_version(request):
     """
     Returns the current version of apprise loaded under the hood

apprise_api/api/templates/base.html

@@ -54,6 +54,10 @@ <h1>{% trans "Apprise API" %}</h1>
           <a class="collection-item" id='cfg-gen' href="{% url 'config' UNIQUE_CONFIG_ID %}"><i class="material-icons">refresh</i>
             {% trans "New Configuration" %}</a>
           {% endif %}
+          {% if STATEFUL_MODE == 'simple' and APPRISE_ADMIN %}
+          <a class="collection-item" id='cfg-list' href="{% url 'config_list' %}"><i class="material-icons">list</i>
+            {% trans "Configuration List" %}</a>
+          {% endif %}
         </ul>
 {% endif %}
         <ul class="collection z-depth-1">

apprise_api/api/templates/config_list.html

@@ -0,0 +1,15 @@
+{% extends 'base.html' %}
+{% load i18n %}
+{% block body %}
+    <h4>{% trans "Configuration List" %}</h4>
+    {% if keys %}
+        <ul class="collection z-depth-1">
+            {% for key in keys %}
+                <a class="collection-item" href="{% url 'config' key %}"><i
+                        class="material-icons">settings</i> {{ key }}</a>
+            {% endfor %}
+        </ul>
+    {% else %}
+        <p>{% blocktrans %}There is no configuration defined.{% endblocktrans %}</p>
+    {% endif %}
+{% endblock %}

apprise_api/api/tests/test_config_cache.py

@@ -23,6 +23,7 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 # THE SOFTWARE.
 import os
+
 from ..utils import AppriseConfigCache
 from ..utils import AppriseStoreMode
 from ..utils import SimpleFileExtension
@@ -112,6 +113,86 @@ def test_apprise_config_io_hash_mode(tmpdir):
     assert acc_obj.get(key) == (content, ConfigFormat.YAML)
 
 
+def test_apprise_config_list_simple_mode(tmpdir):
+    """
+    Test Apprise Config Keys List using SIMPLE mode
+    """
+    # Create our object to work with
+    acc_obj = AppriseConfigCache(str(tmpdir), mode=AppriseStoreMode.SIMPLE)
+
+    # Add a hidden file to the config directory (which should be ignored)
+    hidden_file = os.path.join(str(tmpdir), '.hidden')
+    with open(hidden_file, 'w') as f:
+        f.write('hidden file')
+
+    # Write 5 text configs and 5 yaml configs
+    content_text = 'mailto://test:pass@gmail.com'
+    content_yaml = """
+    version: 1
+    urls:
+         - windows://
+    """
+    text_key_tpl = 'test_apprise_config_list_simple_text_{}'
+    yaml_key_tpl = 'test_apprise_config_list_simple_yaml_{}'
+    text_keys = [text_key_tpl.format(i) for i in range(5)]
+    yaml_keys = [yaml_key_tpl.format(i) for i in range(5)]
+    key = None
+    for key in text_keys:
+        assert acc_obj.put(key, content_text, ConfigFormat.TEXT)
+    for key in yaml_keys:
+        assert acc_obj.put(key, content_yaml, ConfigFormat.YAML)
+
+    # Ensure the 10 configuration files (plus the hidden file) are the only
+    # contents of the directory
+    conf_dir, _ = acc_obj.path(key)
+    contents = os.listdir(conf_dir)
+    assert len(contents) == 11
+
+    keys = acc_obj.keys()
+    assert len(keys) == 10
+    assert sorted(keys) == sorted(text_keys + yaml_keys)
+
+
+def test_apprise_config_list_hash_mode(tmpdir):
+    """
+    Test Apprise Config Keys List using HASH mode
+    """
+    # Create our object to work with
+    acc_obj = AppriseConfigCache(str(tmpdir), mode=AppriseStoreMode.HASH)
+
+    # Add a hidden file to the config directory (which should be ignored)
+    hidden_file = os.path.join(str(tmpdir), '.hidden')
+    with open(hidden_file, 'w') as f:
+        f.write('hidden file')
+
+    # Write 5 text configs and 5 yaml configs
+    content_text = 'mailto://test:pass@gmail.com'
+    content_yaml = """
+    version: 1
+    urls:
+         - windows://
+    """
+    text_key_tpl = 'test_apprise_config_list_simple_text_{}'
+    yaml_key_tpl = 'test_apprise_config_list_simple_yaml_{}'
+    text_keys = [text_key_tpl.format(i) for i in range(5)]
+    yaml_keys = [yaml_key_tpl.format(i) for i in range(5)]
+    key = None
+    for key in text_keys:
+        assert acc_obj.put(key, content_text, ConfigFormat.TEXT)
+    for key in yaml_keys:
+        assert acc_obj.put(key, content_yaml, ConfigFormat.YAML)
+
+    # Ensure the 10 configuration files (plus the hidden file) are the only
+    # contents of the directory
+    conf_dir, _ = acc_obj.path(key)
+    contents = os.listdir(conf_dir)
+    assert len(contents) == 1
+
+    # does not search on hash mode
+    keys = acc_obj.keys()
+    assert len(keys) == 0
+
+
 def test_apprise_config_io_simple_mode(tmpdir):
     """
     Test Apprise Config Disk Put/Get using SIMPLE mode

apprise_api/api/tests/test_manager.py

@@ -23,6 +23,7 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 # THE SOFTWARE.
 from django.test import SimpleTestCase
+from django.test import override_settings
 
 
 class ManagerPageTests(SimpleTestCase):
@@ -34,9 +35,30 @@ def test_manage_status_code(self):
         """
         General testing of management page
         """
-        # No key was specified
+        # No permission to get keys
         response = self.client.get('/cfg/')
-        assert response.status_code == 404
+        assert response.status_code == 403
+
+        with override_settings(APPRISE_ADMIN=True, APPRISE_STATEFUL_MODE='hash'):
+            response = self.client.get('/cfg/')
+            assert response.status_code == 403
+
+        with override_settings(APPRISE_ADMIN=False, APPRISE_STATEFUL_MODE='simple'):
+            response = self.client.get('/cfg/')
+            assert response.status_code == 403
+
+        with override_settings(APPRISE_ADMIN=False, APPRISE_STATEFUL_MODE='disabled'):
+            response = self.client.get('/cfg/')
+            assert response.status_code == 403
+
+        with override_settings(APPRISE_ADMIN=True, APPRISE_STATEFUL_MODE='disabled'):
+            response = self.client.get('/cfg/')
+            assert response.status_code == 403
+
+        # But only when the setting is enabled
+        with override_settings(APPRISE_ADMIN=True, APPRISE_STATEFUL_MODE='simple'):
+            response = self.client.get('/cfg/')
+            assert response.status_code == 200
 
         # An invalid key was specified
         response = self.client.get('/cfg/**invalid-key**')

apprise_api/api/urls.py

@@ -38,6 +38,9 @@
     re_path(
         r'^cfg/(?P<key>[\w_-]{1,128})/?$',
         views.ConfigView.as_view(), name='config'),
+    re_path(
+        r'^cfg/?$',
+        views.ConfigListView.as_view(), name='config_list'),
     re_path(
         r'^add/(?P<key>[\w_-]{1,128})/?$',
         views.AddView.as_view(), name='add'),

apprise_api/api/utils.py

@@ -711,6 +711,24 @@ def path(self, key):
         else:   # AppriseStoreMode.SIMPLE
             return (self.root, key)
 
+    def keys(self):
+        """
+        Returns a list of keys that are currently stored
+        """
+        keys = []
+        if self.mode != AppriseStoreMode.SIMPLE:
+            return keys
+
+        for filename in sorted(os.listdir(self.root)):
+            if filename.startswith('.'):
+                continue
+            path = os.path.join(self.root, filename)
+            if os.path.isfile(path):
+                key_name = os.path.splitext(filename)[0]
+                keys.append(key_name)
+
+        return keys
+
 
 # Initialize our singleton
 ConfigCache = AppriseConfigCache(

apprise_api/api/views.py

@@ -38,6 +38,7 @@
 from .payload_mapper import remap_fields
 from .utils import parse_attachments
 from .utils import ConfigCache
+from .utils import AppriseStoreMode
 from .utils import apply_global_filters
 from .utils import send_webhook
 from .utils import healthcheck
@@ -114,7 +115,6 @@ class ResponseCode(object):
     no_content = 204
     bad_request = 400
     no_access = 403
-    not_found = 404
     method_not_allowed = 405
     method_not_accepted = 406
     expectation_failed = 417
@@ -253,6 +253,43 @@ def get(self, request, key):
         })
 
 
+@method_decorator(never_cache, name='dispatch')
+class ConfigListView(View):
+    """
+    A Django view used to list all configuration keys
+    """
+    template_name = 'config_list.html'
+
+    def get(self, request):
+        """
+        Handle a GET request
+        """
+        # Detect the format our response should be in
+        json_response = \
+            MIME_IS_JSON.match(
+                request.content_type
+                if request.content_type
+                else request.headers.get(
+                    'accept', request.headers.get(
+                        'content-type', ''))) is not None
+
+        if not (settings.APPRISE_ADMIN and settings.APPRISE_STATEFUL_MODE == AppriseStoreMode.SIMPLE):
+            msg = _('The site has been configured to deny this request')
+            status = ResponseCode.no_access
+            return HttpResponse(msg, status=status, content_type='text/plain') \
+                if not json_response else JsonResponse({
+                    'error': msg,
+                },
+                encoder=JSONEncoder,
+                safe=False,
+                status=status,
+            )
+
+        return render(request, self.template_name, {
+            'keys': ConfigCache.keys(),
+        })
+
+
 @method_decorator(never_cache, name='dispatch')
 class AddView(View):
     """

apprise_api/core/settings/__init__.py

@@ -89,6 +89,7 @@
                 'api.context_processors.unique_config_id',
                 'api.context_processors.stateful_mode',
                 'api.context_processors.config_lock',
+                'api.context_processors.admin_enabled',
                 'api.context_processors.apprise_version',
             ],
         },
@@ -284,3 +285,9 @@
 # Define the number of attachments that can exist as part of a payload
 # Setting this to zero disables the limit
 APPRISE_MAX_ATTACHMENTS = int(os.environ.get('APPRISE_MAX_ATTACHMENTS', 6))
+
+# Allow Admin mode:
+# - showing a list of configuration keys (when STATEFUL_MODE is set to simple)
+APPRISE_ADMIN = \
+    os.environ.get("APPRISE_ADMIN", 'no')[0].lower() in (
+        'a', 'y', '1', 't', 'e', '+')