Permission sets for community lexicon bookmarks

Lexicon Community
1

Hello! I’ve implemented the lexicon community’s bookmark lexicon for sill.social, but I’ve been using the transition:generic scope while Bluesky’s permission sets get fully worked out. I’d also like permission sets for the bookmarks lexicon. I’d like to propose two: a read-only scope and a full manage scope. I modeled these roughly after standard.site’s permission set.

First: the read-only scope, community.lexicon.bookmarks.authViewBookmarks:

{
  "$type": "com.atproto.lexicon.schema",
  "lexicon": 1,
  "id": "community.lexicon.bookmarks.authViewBookmarks",
  "defs": {
    "main": {
      "type": "permission-set",
      "title": "Read bookmarks",
      "detail": "View the account's saved bookmarks.",
      "permissions": [
        {
          "type": "permission",
          "resource": "rpc",
          "inheritAud": true,
          "lxm": [
            "community.lexicon.bookmarks.getActorBookmarks"
          ]
        }
      ]
    }
  }
}

And the manage scope, community.lexicon.bookmarks.authManageBookmarks:

{
  "$type": "com.atproto.lexicon.schema",
  "lexicon": 1,
  "id": "community.lexicon.bookmarks.authManageBookmarks",
  "defs": {
    "main": {
      "type": "permission-set",
      "title": "Manage bookmarks",
      "detail": "View, create, edit, and delete the account's saved bookmarks.",
      "permissions": [
        {
          "type": "permission",
          "resource": "rpc",
          "inheritAud": true,
          "lxm": [
            "community.lexicon.bookmarks.getActorBookmarks"
          ]
        },
        {
          "type": "permission",
          "resource": "repo",
          "collection": [
            "community.lexicon.bookmarks.bookmark"
          ]
        }
      ]
    }
  }
}

I don’t think there’s a strong case for read and write without delete and update. Since we’re using rpc resources, it does need an aud, so we set inheritAud to true.

One could argue this is unnecessary since adding the RPC/repo scopes are straightforward for a lexicon space this small. However, the OAuth consent screen presents much better when you use permission sets. Rather than a generic message saying my app can publish changes to your repository, it would be clear that the service can only access bookmarks.

Thoughts?

EDIT: renamed to authViewBookmarks and authManageBookmarks to match existing convention.

3 Likes
2

This looks good to me.

1 Like
3

Having Lexicon community permission-sets makes sense to me! A couple small style notes:

As a soft norm, I think it is good to have permission sets start with “auth” to make it clear what they are from the name (eg, not an API endpoint, not a record type). So i’d call it community.lexicon.bookmarks.authManageBookmarks (for example).

For lexicon community permission sets, I think putting them in the NSID groups themselves usually makes sense, so having them under community.lexicon.bookmarks.* is good.

There is some potential confusion with “read” permission. If I understand/recall correctly, these bookmark records are public data, so they are generally available without authentication. The community.lexicon.bookmarks.getActorBookmarks XRPC endpoint might also be provided as a public HTTP API endpoint, not requiring authentication; or require authentication. title and detail could clarify that. I’d also use the verb “view”, so community.lexicon.bookmarks.authViewBookmarks.

It would probably be good to have the title and detail fields internationalized in a couple popular languages. I don’t think lexicon community has policies on this currently (eg, which languages to start with, and whether machine translation is acceptable as a starting point). I’d probably go with at least Japanese, using machine translation. This could be done as an additional/final step (eg, in case the title/detail text in English gets iterated on), or even after initial publication.

1 Like
4

Thanks Bryan! All great notes.

Renaming makes sense. authViewBookmarks and authManageBookmarks works for me.

Bookmarks are public data at the moment of course, theoretically this permission set could adapt to accessing private bookmarks once permissioned data lands? But I don’t know enough about where you’re going to know if permission sets are even the interface for that.

Don’t know enough about the community standards to know if there’s a machine translation standard, but happy to implement whatever is needed there.

1 Like