Documentation for the new hook: https://docs.datasette.io/en/latest/plugin_hooks.html#register-permissions-datasette

Idea: a /-/permissions introspection endpoint for listing registered permissions

I'm going to address those ideas for changes to the permission_allowed() in a separate issue.

What would it take for the register_permissions() hook to be something I'm comfortable landing?

I think it's mainly that the list of permissions it provides should Do More Stuff:

• Participate in unit tests, in particular this one:

https://github.com/simonw/datasette/blob/e539c1c024bc62d88df91d9107cbe37e7f0fe55f/tests/conftest.py#L79-L102

• That new default option should be respected - maybe if you omit default= from a call to permission_allowed() it could fall back on the default from there?
• Log a warning if you attempt to check a permission that wasn't registered

Then I can use the permissions - in particular their metadata - to help implement his:

• 1636

Draft docs for the new plugin hook: https://datasette--1940.org.readthedocs.build/en/1940/plugin_hooks.html#register-permissions-datasette

Made a draft PR so ReadTheDocs would deploy my new documentation somewhere.

I'm going to try a spike in a branch with datasette.action_allowed(...) and a register_permissions() plugin hook, to see what they look like.

I think action_allowed is my favourite, even though there's a little bit of concept overlap with table_actions and database_actions.

I never really liked those plugin hook names much to be honest, especially since they are inconsistent with menu_links:

https://github.com/simonw/datasette/blob/d67f812b7327c7075732688f3df728807503dc58/datasette/hookspecs.py#L123-L135

Another option:

python if await datasette.actor_can(actor, "insert-data"...)

Asked ChatGPT for some alternative names, I didn't like any of them:

is_permission_granted
has_permission
check_permission
is_action_allowed
check_access_permission
permission_check
validate_permission
check_actor_permission
verify_permission
check_authorization

It's also referenced in this plugin hook: python @hookspec def permission_allowed(datasette, actor, action, resource): """Check if actor is allowed to perform this action - return True, False or None""" But more importantly, in these ones: ```python @hookspec def table_actions(datasette, actor, database, table, request): """Links for the table actions menu"""

@hookspec def database_actions(datasette, actor, database, request): """Links for the database actions menu""" ``` So the word "action" is already used within Datasette to refer to those things - which are almost but not quite the same as actions-as-permissions: many of the things that show up in those menus relate to permissions the user has, but not necessarily all of them.

Should I rename "permission" to "action" elsewhere too? Maybe have a register_actions(...) plugin hook instead of adding register_permissions(...)?

What else could the word "action" mean?

Currently it's used in the codebase to refer to GitHub Actions, and for code like this: python if await self.permission_allowed( actor=actor, action="view-instance", default=True ): Which is already revealing the confusion between "permission" and "action".

One option: python async def action_allowed(self, actor, action, database=None, resource=None): action_allowed fixes the permission v.s. action thing a bit, and is a new name that doesn't clash with the existing method. I dropped default because that's now a property of the permission itself. table is now called resource and database is a separate parameter.

What if I came up with a new method name for this, which could co-exist with the old one while that old one was deprecated?

Extracted a TIL: https://til.simonwillison.net/github/github-code-search-api-uses

This search is better:

datasette permission_allowed -user:simonw -path:datasette/** -path:docs/** -path:tests/** language:python

That returns 11 results: https://cs.github.com/?scopeName=All+repos&scope=&q=datasette+permission_allowed+-user%3Asimonw+-path%3Adatasette%2F+-path%3Adocs%2F+-path%3Atests%2F**+language%3Apython

3 are forks of my repos. The rest are all by four users:

• 20after4/ddd
• emg110/datasette-graphql
• next-LI/datasette-csv-importer
• next-LI/datasette-demo
• next-LI/datasette-live-config
• next-LI/datasette-live-permissions
• next-LI/datasette-search-all
• next-LI/datasette-surveys
• next-LI/datasette-write
• rclement/datasette-dashboards

This code search shows a bunch of repos I don't know about that would be affected by this change: https://cs.github.com/?scopeName=All+repos&scope=&q=datasette+permission_allowed+-user%3Asimonw#

These (and likely more):

Repositories

• 20after4/ddd
• next-LI/datasette-csv-importer
• digital-land/datasette
• mroswell/datasette
• next-LI/datasette-live-config
• keladhruv/datasette
• RhetTbull/datasette
• chriswedgwood/datasette
• boan-anbo/datasette
• MattTriano/datasette
• incadenza/datasette
• robdyke/datasette
• ctb/datasette
• eyeseast/datasette
• symbol-management/api-match-audit

Actually a lot of those are forks of Datasette itself - so maybe this is manageable?

Would be nice if I could come up with a GitHub search that excluded any repos with "datasette" as their exact name.

https://docs.github.com/en/search-github/github-code-search/understanding-github-code-search-syntax#using-qualifiers says:

Note: The new code search beta does not currently support regular expressions or partial matching for repository names, so you will have to type the entire repository name (including the user prefix) for the repo: qualifier to work.

Moving the concept of the default for the permission into this registry warrants a redesign of this method anyway:

https://github.com/simonw/datasette/blob/e539c1c024bc62d88df91d9107cbe37e7f0fe55f/datasette/app.py#L706

python Permission = collections.namedtuple( "Permission", ("name", "abbr", "takes_database", "takes_table", "default") ) I don`t think that design is quite right.

• Elsewhere in the code the concept is called an "action" rather than a "permission" - I think I can stick with the Permission name here though, it's pretty clear
• takes_database - is takes_ the right verb here?
• takes_table can also refer to a SQL view or a canned named query

A question that was raised by the work in #1938 is whether you should be able to grant a permission like insert-row at the instance or database level - and if so, what does that look like? I think you should be able to do that, it doesn't make sense to have to grant it explicitly for every single table.

So maybe takes_table and takes_database are the right names here? But table is still bad because it doesn't reflect views and canned queries.

One thought is to use resource - but that will require a bunch of breaking changes to the existing APIs which treat resource as a tuple. Now's the best time to do that though before Datasette 1.0.

I originally added permissions.py for the permission debug tool in https://github.com/simonw/datasette/commit/c51d9246b996a2831c9bd6a1e205f6cb48b9a5f3 - I don't think anything else uses it yet.

• 1881

One concern I have about this: there are a bunch of existing plugins that do stuff with permissions that won't currently be using this hook.

Do I break those plugins, forcing new releases of them for compatibility with Datasette 1.0?

Or maybe I keep them working, but until they've upgraded to register their permissions there are things about them that won't work - e.g. you won't be able to configure their permissions in metadata.yml until they release something that does this hook.

Best thing is probably for me to get this working in core first and then evaluate the impact it would have on existing plugins once I have some running code.