Document the ds_actor signed cookie

[simonw]

Most authentication plugins (https://github.com/simonw/datasette-auth-github for example) are likely to work by setting the ds_actor signed cookie, which is already magically decoded and supported by default Datasette here:

datasette/datasette/actor_auth_cookie.py

Lines 1 to 13 in 4fa7cf6

	from datasette import hookimpl
	from itsdangerous import BadSignature
	from http.cookies import SimpleCookie
	@hookimpl
	def actor_from_request(datasette, request):
	if "ds_actor" not in request.cookies:
	return None
	try:
	return datasette.unsign(request.cookies["ds_actor"], "actor")
	except BadSignature:
	return None

I should document this.

[simonw]

I should probably add a utility function for setting that cookie - right now the only code that does that is here:

datasette/datasette/views/special.py

Lines 63 to 76 in dfff34e

	if secrets.compare_digest(token, self.ds._root_token):
	self.ds._root_token = None
	cookie = SimpleCookie()
	cookie["ds_actor"] = self.ds.sign({"id": "root"}, "actor")
	cookie["ds_actor"]["path"] = "/"
	response = Response(
	body="",
	status=302,
	headers={
	"Location": "/",
	"set-cookie": cookie.output(header="").lstrip(),
	},
	)
	return response

[simonw]

Also a good reminder that I need a set_cookie() function (#795) so I don't have to mess around with SimpleCookie directly.

[simonw]

https://datasette.readthedocs.io/en/latest/authentication.html#the-ds-actor-cookie