Add permissions checks

[simonw]

Initially using an "allow" block.

Split from #2 (comment)

[simonw]

I may need to borrow this function from Datasette for the tests:

def assert_permissions_checked(datasette, actions):
    # actions is a list of "action" or (action, resource) tuples
    for action in actions:
        if isinstance(action, str):
            resource = None
        else:
            action, resource = action
        assert [
            pc
            for pc in datasette._permission_checks
            if pc["action"] == action and pc["resource"] == resource
        ], """Missing expected permission check: action={}, resource={}
        Permission checks seen: {}
        """.format(
            action, resource, json.dumps(list(datasette._permission_checks), indent=4),
        )

https://github.com/simonw/datasette/blob/1f6a134369e6a7efaae9db469f15b1dd2b7f3709/tests/fixtures.py#L836-L851

It's not importable (it lives in fixtures.py and not in the datasette package that gets packaged for PyPI) - maybe I should fix that in Datasette by adding a from datasette.utils.testing module.

[simonw]

Rethinking how default permissions should work: if you install the plugin locally on your laptop, it should work without authentication.

You can then control permissions using "allow" blocks, as described in https://datasette.readthedocs.io/en/stable/authentication.html#defining-permissions-with-allow-blocks - which can be added to the plugin configuration. That would look like this:

{
    "plugins": {
        "datasette-insert-api": {
            "allow": {
                "id": "root"
            }
         }
    }
}

[simonw]

The trickiest thing here is going to be the documentation. I think I'll describe how to use this with datastte-auth-tokens.

[simonw]

Here's the documentation I wrote for finely grained permissions, which are not yet implemented:

---

Finely grained permissions

Using an "allow" block as described above grants full permission to the features enabled by the API.

The API implements several new Datasett permissions, which other plugins can use to make more finely grained decisions.

The full set of permissions are as follows:

• insert-api:all - all permissions - this is used by the "allow" block described above. Argument: database_name
• insert-api:insert-update - the ability to insert data into an existing table, or to update data by its primary key. Arguments: (database_name, table_name)
• insert-api:create-table - the ability to create a new table. Argument: database_name
• insert-api:alter-table - the ability to add columns to an existing table (using ?alter=1). Arguments: (database_name, table_name)

You can use plugins like datasette-permissions-sql to hook into these more detailed permissions for finely grained control over what actions each authenticated actor can take.

Plugins that implement the permission_allowed() plugin hook can take full control over these permission decisions.

[simonw]

Documentation so far: https://github.com/simonw/datasette-insert-api/tree/b5342147a0490829108a808c33bb8fd513c2296a#permissions-and-authentication

[simonw]

Released 0.3 with basic "allow" permissions. Next release can have the finely grained permissions.