From 060a56735c1d3bde0a4c7674e82b5f45bef34dee Mon Sep 17 00:00:00 2001
From: Simon Willison <swillison@gmail.com>
Date: Sat, 30 May 2020 13:24:00 -0700
Subject: [PATCH] actor_from_request and permission_allowed hookspecs, refs
 #699

---
 datasette/hookspecs.py | 10 ++++++++++
 docs/plugins.rst       | 37 +++++++++++++++++++++++++++++++++++++
 2 files changed, 47 insertions(+)

diff --git a/datasette/hookspecs.py b/datasette/hookspecs.py
index c2fc012696..65c1c85946 100644
--- a/datasette/hookspecs.py
+++ b/datasette/hookspecs.py
@@ -58,3 +58,13 @@ def register_output_renderer(datasette):
 @hookspec
 def register_facet_classes():
     "Register Facet subclasses"
+
+
+@hookspec
+def actor_from_request(datasette, request):
+    "Return an actor dictionary based on the incoming request"
+
+
+@hookspec
+def permission_allowed(actor, action, resource_type, resource_identifier):
+    "Check if actor is allowed to perfom this action - return True, False or None"
diff --git a/docs/plugins.rst b/docs/plugins.rst
index f08f121771..09e8f5e350 100644
--- a/docs/plugins.rst
+++ b/docs/plugins.rst
@@ -941,3 +941,40 @@ This example plugin adds a ``x-databases`` HTTP header listing the currently att
         return wrap_with_databases_header
 
 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:
+
+actor_from_request(datasette, request)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``datasette`` - :ref:`internals_datasette`
+    You can use this to access plugin configuration options via ``datasette.plugin_config(your_plugin_name)``, or to execute SQL queries.
+
+``request`` - object
+    The current HTTP :ref:`internals_request`.
+
+This is part of Datasette's authentication and permissions system. The function should attempt to authenticate an actor (either a user or an API actor of some sort) based on information in the request.
+
+If it cannot authenticate an actor, it should return ``None``. Otherwise it should return a dictionary representing that actor.
+
+.. _plugin_permission_allowed:
+
+permission_allowed(datasette, actor, action, resource_type, resource_identifier)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``datasette`` - :ref:`internals_datasette`
+    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`.
+
+``action`` - string
+    The action to be performed, e.g. ``"edit-table"``.
+
+``resource_type`` - string
+    The type of resource being acted on, e.g. ``"table"``.
+
+``resource`` - string
+    An identifier for the individual resource, e.g. the name of the table.
+
+Called to check that an actor has permission to perform an action on a resource. Can return ``True`` if the action is allowed, ``False`` if the action is not allowed or ``None`` if the plugin does not have an opinion one way or the other.