Link to datasett-auth-tokens and datasette-permissions-sql in docs, r…

…efs #806
simonw · Jun 12, 2020 · 793a52b · 793a52b
1 parent 1d2e8e0
commit 793a52b
Show file tree

Hide file tree

Showing 5 changed files with 25 additions and 12 deletions.
diff --git a/docs/authentication.rst b/docs/authentication.rst
@@ -19,7 +19,7 @@ Every request to Datasette has an associated actor value, available in the code
 
 The actor dictionary can be any shape - the design of that data structure is left up to the plugins. A useful convention is to include an ``"id"`` string, as demonstrated by the "root" actor below.
 
-Plugins can use the :ref:`plugin_actor_from_request` hook to implement custom logic for authenticating an actor based on the incoming HTTP request.
+Plugins can use the :ref:`plugin_hook_actor_from_request` hook to implement custom logic for authenticating an actor based on the incoming HTTP request.
 
 .. _authentication_root:
 
@@ -314,7 +314,7 @@ Checking permissions in plugins
 
 Datasette plugins can check if an actor has permission to perform an action using the :ref:`datasette.permission_allowed(...)<datasette_permission_allowed>` method.
 
-Datasette core performs a number of permission checks, :ref:`documented below <permissions>`. Plugins can implement the :ref:`plugin_permission_allowed` plugin hook to participate in decisions about whether an actor should be able to perform a specified action.
+Datasette core performs a number of permission checks, :ref:`documented below <permissions>`. Plugins can implement the :ref:`plugin_hook_permission_allowed` plugin hook to participate in decisions about whether an actor should be able to perform a specified action.
 
 .. _authentication_actor_matches_allow:
 

diff --git a/docs/changelog.rst b/docs/changelog.rst
@@ -27,7 +27,7 @@ You'll need to install plugins if you want full user accounts, but default Datas
     INFO:     Application startup complete.
     INFO:     Uvicorn running on http://127.0.0.1:8001 (Press CTRL+C to quit)
 
-Plugins can implement new ways of authenticating users using the new :ref:`plugin_actor_from_request` hook.
+Plugins can implement new ways of authenticating users using the new :ref:`plugin_hook_actor_from_request` hook.
 
 Permissions
 ~~~~~~~~~~~
@@ -52,7 +52,7 @@ You can use the new ``"allow"`` block syntax in ``metadata.json`` (or ``metadata
 
 See :ref:`authentication_permissions_allow` for more details.
 
-Plugins can implement their own custom permission checks using the new :ref:`plugin_permission_allowed` hook.
+Plugins can implement their own custom permission checks using the new :ref:`plugin_hook_permission_allowed` hook.
 
 A new debug page at ``/-/permissions`` shows recent permission checks, to help administrators and plugin authors understand exactly what checks are being performed. This tool defaults to only being available to the root user, but can be exposed to other users by plugins that respond to the ``permissions-debug`` permission. (`#788 <https://github.com/simonw/datasette/issues/788>`__)
 

diff --git a/docs/ecosystem.rst b/docs/ecosystem.rst
@@ -87,6 +87,16 @@ datasette-auth-github
 
 `datasette-auth-github <https://github.com/simonw/datasette-auth-github>`__ adds an authentication layer to Datasette. Users will have to sign in using their GitHub account before they can view data or interact with Datasette. You can also use it to restrict access to specific GitHub users, or to members of specified GitHub `organizations <https://help.github.com/en/articles/about-organizations>`__ or `teams <https://help.github.com/en/articles/organizing-members-into-teams>`__.
 
+datasette-auth-tokens
+---------------------
+
+`datasette-auth-tokens <https://tokens.com/simonw/datasette-auth-tokens>`__ provides a mechanism for creating secret API tokens that can then be used with Datasette's :ref:`authentication` system.
+
+datasette-permissions-sql
+---------------------
+
+`datasette-permissions-sql <https://tokens.com/simonw/datasette-permissions-sql>`__ lets you configure Datasette permissions checks to use custom SQL queries, which means you can make permisison decisions based on data contained within your databases.
+
 datasette-upload-csvs
 ---------------------
 

diff --git a/docs/internals.rst b/docs/internals.rst
@@ -219,7 +219,7 @@ await .permission_allowed(actor, action, resource=None, default=False)
 
 Check if the given actor has :ref:`permission <authentication_permissions>` to perform the given action on the given resource.
 
-Some permission checks are carried out against :ref:`rules defined in metadata.json <authentication_permissions_metadata>`, while other custom permissions may be decided by plugins that implement the :ref:`plugin_permission_allowed` plugin hook.
+Some permission checks are carried out against :ref:`rules defined in metadata.json <authentication_permissions_metadata>`, while other custom permissions may be decided by plugins that implement the :ref:`plugin_hook_permission_allowed` plugin hook.
 
 If neither ``metadata.json`` nor any of the plugins provide an answer to the permission query the ``default`` argument will be returned.
 

diff --git a/docs/plugins.rst b/docs/plugins.rst
@@ -25,9 +25,8 @@ Things you can do with plugins include:
 * Customize how database values are rendered in the Datasette interface, for example
   `datasette-render-binary <https://github.com/simonw/datasette-render-binary>`__ and
   `datasette-pretty-json <https://github.com/simonw/datasette-pretty-json>`__.
-* Wrap the entire Datasette application in custom ASGI middleware to add new pages
-  or implement authentication, for example
-  `datasette-auth-github <https://github.com/simonw/datasette-auth-github>`__.
+* Customize how Datasette's authentication and permissions systems work, for example `datasette-auth-tokens <https://github.com/simonw/datasette-auth-tokens>`__ and
+  `datasette-permissions-sql <https://github.com/simonw/datasette-permissions-sql>`__.
 
 .. _plugins_installing:
 
@@ -996,7 +995,7 @@ This example plugin adds a ``x-databases`` HTTP header listing the currently att
 
 Examples: `datasette-auth-github <https://github.com/simonw/datasette-auth-github>`_, `datasette-search-all <https://github.com/simonw/datasette-search-all>`_, `datasette-media <https://github.com/simonw/datasette-media>`_
 
-.. _plugin_actor_from_request:
+.. _plugin_hook_actor_from_request:
 
 actor_from_request(datasette, request)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -1055,7 +1054,9 @@ Instead of returning a dictionary, this function can return an awaitable functio
 
         return inner
 
-.. _plugin_permission_allowed:
+Example: `datasette-auth-tokens <https://github.com/simonw/datasette-auth-tokens>`_
+
+.. _plugin_hook_permission_allowed:
 
 permission_allowed(datasette, actor, action, resource)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -1064,7 +1065,7 @@ permission_allowed(datasette, actor, action, resource)
     You can use this to access plugin configuration options via ``datasette.plugin_config(your_plugin_name)``, or to execute SQL queries.
 
 ``actor`` - dictionary
-    The current actor, as decided by :ref:`plugin_actor_from_request`.
+    The current actor, as decided by :ref:`plugin_hook_actor_from_request`.
 
 ``action`` - string
     The action to be performed, e.g. ``"edit-table"``.
@@ -1110,4 +1111,6 @@ Here's an example that allows users to view the ``admin_log`` table only if thei
 
         return inner
 
-See :ref:`permissions` for a full list of permissions that are included in Datasette core.
+See :ref:`built-in permissions <permissions>` for a full list of permissions that are included in Datasette core.
+
+Example: `datasette-permissions-sql <https://github.com/simonw/datasette-permissions-sql>`_