~ knotless Search/
↑↓ move↵ open⇧↵ all results
0
0
290 lines · 16.4 KB Raw History

OAuth: permission sets

A permission set is a Lexicon schema an app's author publishes, naming a bundle of repo, rpc and space permissions under the set's own namespace, with a title and description for the people asked to grant it (atproto/permission.md, "Permission Sets"; atproto/lexicon.md, "Permission Set"). A client asks for one with an include: scope: include:com.example.authFull, or with an audience for the set's rpc permissions that inherit one, include:com.example.authFull?aud=did:web:api.example.com%23svc.

This page says how the server resolves a set, what it takes at PAR, what the authorization page is given of it, and how a token's scope holds it. Everything OAUTH.md and OAUTH-SCOPES.md say holds for these scopes too, where this page does not say otherwise; what the consent view shows of a set is in OAUTH-PAGES.md.

Sources

This section is informative.

FileIsLicence
atproto/permission.mdpermissions, the include resource, permission sets, their namespace authority, resolution and cachingCC-BY, atproto/LICENSE.txt
atproto/lexicon.mdthe permission-set and permission types; Lexicon publication and resolutionCC-BY, atproto/LICENSE.txt
atproto/nsid.mdan NSID's authority and nameCC-BY, atproto/LICENSE.txt
spaces/proposal.mdspace permissions in a set ("Permission sets")spaces/README.md

The rules those leave open are the reference's, probed, and where the reference departs from them it says so below ("Where the reference departs from the specs").

The include: scope

An include scope parses when it has an nsid, positional or as a parameter, that is an NSID, and at most an aud, a DID with a # service fragment (percent-decoded as the scope's parameters are; not *), and no other parameter. One that does not parse is dropped at PAR, as any scope token the server does not know is (OAUTH.md, "Pushed authorization requests"); it must still be declared by the client, as every token must.

Resolving a set

A set is resolved by its NSID, as atproto/lexicon.md ("Lexicon Publication and Resolution") says:

  1. The authority's DID. The NSID's authority is its segments but the last, reversed: com.example.calendar.basePermissions has the authority calendar.example.com. The server looks up the DNS TXT records of _lexicon.<authority>, and takes the one whose text begins did=, the rest of it being the DID. None, or more than one, and the set does not resolve. The server looks at no other name.

    With PDS_LEXICON_AUTHORITY_DID set to a DID, the server looks up no DNS record: that DID is every NSID's authority, as the reference's setting of the same name makes it.

    Note: it is for development and testing, and for a server that takes its lexicons from one place it trusts.

  2. The DID's document, as the server resolves any account's (IDENTITY.md): its #atproto key and its #atproto_pds service endpoint. Without either, the set does not resolve.

  3. The record. GET <endpoint>/xrpc/com.atproto.sync.getRecord with did, collection=com.atproto.lexicon.schema and rkey=<the NSID>, under the rules of the server's other outbound requests (PROXY.md: SSRF protection unless PDS_DISABLE_SSRF_PROTECTION=true, no redirects followed), within 10 seconds, its answer at most 1 MiB. Anything but 200 with a CAR file, and the set does not resolve.

  4. Its proof, as atproto/sync.md has a consumer check one: the CAR's root is a commit whose did is the DID and whose signature the document's #atproto key verifies, and the commit's MST holds com.atproto.lexicon.schema/<the NSID> at a CID whose block, in the CAR, hashes to it. Anything else, and the set does not resolve.

  5. The document, the record's value:

    • $type com.atproto.lexicon.schema, lexicon 1, id the NSID, and defs an object with a main object; else the set does not resolve;
    • defs.main.type permission-set; else it is not a set;
    • permissions an array of objects, each with type: "permission" and a resource string, and every field of each a string, a number, a boolean, or an array of those; title and detail, if given, strings; title:lang and detail:lang, if given, objects whose keys are language tags (atproto/lexicon.md, language format) and whose values are strings. Else the set does not resolve.

Caching. A set resolved is kept, shared by every account and session, and resolved again when it is asked for once an hour has passed since it was last resolved; if that fails, the set kept is used, for up to 90 days from when it last resolved. A set that does not resolve is remembered for 5 minutes, and resolving it is not tried again before then. The server keeps at most 10000 sets, dropping the one least recently asked for beyond that. What it keeps is in memory: after a restart every set is resolved again.

Note: atproto/permission.md asks for these bounds: a stale time no shorter than an access token's life and no longer than 24 hours, and an expiry of 90 days.

What a set grants

A set grants its permissions that are valid, each as the granular permission of OAUTH-SCOPES.md ("What a scope allows"). A permission is dropped, alone, and the rest kept, when:

  • its resource is not repo, rpc or space (blob, account and identity permissions are not for sets, and others are unknown);
  • it has a field its resource does not take: for repo, collection (required, an array of one or more NSIDs) and action (an array of create, update, delete); for rpc, lxm (required, an array of one or more NSIDs), aud and inheritAud; for space, the parameters of OAUTH-SCOPES.md ("Spaces", "Which parse"): spaceType (required), authority and skey, each a string, and collection, action and manage, each an array of one or more strings;
  • a field's value is not as above, or as that table allows for a space permission; or a repo collection or an rpc method is *;
  • an rpc permission's aud is anything but *;
  • inheritAud is anything but true; or it is true and the permission has an aud too, or the include: has no aud. With inheritAud: true, no aud and an include: aud, the permission's audience is the include:'s;
  • an rpc permission has neither an aud nor inheritAud with an include: aud (an rpc permission needs one audience);
  • lxm is * and aud is *;
  • any of a repo permission's collections or an rpc permission's methods, or a space permission's spaceType, is outside the set's namespace (atproto/permission.md, "Namespace Authority"): each must begin with the set's NSID up to and including its last ., and be longer than that, compared character by character, case and all. The set com.example.calendar.basePermissions grants com.example.calendar.event and com.example.calendar.sub.thing, not com.example.other.x nor com.example.calendar itself. A spaceType of * is outside every namespace. A space permission's collections are not asked: they may be *, or under any namespace (spaces/proposal.md, "Permission sets").

A set whose permissions are all dropped resolves, and grants nothing.

As scope strings. A set's grant is written as scope strings, in the order of its permissions, one for each kept:

  • repo: the collections, each once; one alone is written after repo: (repo:com.example.post), several as repo?collection=… with each in turn, sorted. Then the actions, after ? (or &), each as action=… in the order create, update, delete, each once; none written when the permission gives all three or none. An empty action drops the permission.
  • rpc: the methods, each once and sorted; one alone after rpc:, several as rpc?lxm=…&lxm=…. Then aud=<audience>, the audience percent-encoded but for letters, digits, -_.!~*'(), : and /: so # is written %23, and *, : and / are as they are.
  • space: as OAUTH-SCOPES.md writes a space: token again ("Spaces", "The token's scope"), from the permission's fields, their defaults left out: authority self and skey * are not written, nor the four default actions.
Permission (com.example.calendar.basePermissions)Scope string
repo, collection: [com.example.calendar.event]repo:com.example.calendar.event
repo, collection: [com.example.calendar.event, com.example.calendar.attendee]repo?collection=com.example.calendar.attendee&collection=com.example.calendar.event
repo, collection: [com.example.calendar.event], action: [delete, create]repo:com.example.calendar.event?action=create&action=delete
repo, collection: [com.example.calendar.event], action: [create, update, delete]repo:com.example.calendar.event
rpc, lxm: [com.example.calendar.getEvents], aud: "*"rpc:com.example.calendar.getEvents?aud=*
rpc, lxm: [com.example.calendar.getEvents, com.example.calendar.addEvent], inheritAud: true, with include:…?aud=did:web:api.example.com%23calrpc?lxm=com.example.calendar.addEvent&lxm=com.example.calendar.getEvents&aud=did:web:api.example.com%23cal
space, spaceType: com.example.calendar.spacespace:com.example.calendar.space
space, spaceType: com.example.calendar.space, authority: self, action: [delete, read, create, update]space:com.example.calendar.space
space, spaceType: com.example.calendar.space, authority: did:plc:abc, skey: main, collection: [org.other.note, *], action: [create, read]space:com.example.calendar.space?authority=did:plc:abc&skey=main&collection=*&action=read&action=create
space, spaceType: com.example.calendar.space, collection: [com.example.calendar.event], manage: [delete, create]space:com.example.calendar.space?collection=com.example.calendar.event&manage=create&manage=delete

At PAR

An include: scope the client declares, that parses, is resolved at PAR, as step 15 of OAUTH.md's checks; each distinct NSID once:

  • a set that does not resolve: 400 invalid_scope;
  • a document that resolves and is not a set: 400 invalid_scope.

The request keeps the scope as given, its include: tokens unexpanded.

The authorization page and consent

__authorizeData.scope holds the include: tokens as kept, unexpanded, and __authorizeData.permissionSets is an object with a key for each distinct NSID the scope includes, its value the document's defs.main as published, every field kept, as the reference gives it. The page resolves each set again (from what is kept, above); if one no longer resolves, the page is a 400 error page invalid_scope.

Consent narrows the scope as OAUTH.md says, token by token: an include: token is kept or dropped whole. Nothing is resolved at consent.

The token's scope

At the code grant the server resolves each set again (from what is kept); one that does not resolve is 400 invalid_request, as the reference answers. The session's scope is then expanded: each include: token, in the scope's order, is replaced by the scope strings of its grant, and these come first, followed by the scope's other tokens in their order, with nothing removed as a duplicate. Each space: string of the expansion is then rewritten as any space: token is (OAUTH-SCOPES.md, "Spaces", "The token's scope"). That is the token answer's scope, and what the session's tokens allow (OAUTH-SCOPES.md): an include: token itself allows nothing.

At each refresh the session's scope is expanded again from its kept include: tokens, so a set changed since reaches the session, as atproto/permission.md intends; a set that no longer resolves and is not kept leaves the session's last expansion as it was. The refresh's answer carries the new expansion as its scope.

Each session keeps, durably (OAUTH.md, "Durability"), its scope as consented, include: tokens and all, and its current expansion.

Where the reference departs from the specs

The reference does these, which the specs this page rests on say otherwise; the server follows the specs, and the harness does not compare them, but holds the server to this page:

The referenceThe specThe server
resolves a kept set again after 5 minutesatproto/permission.md: a stale time no shorter than an access token's lifeafter an hour
keeps a set that resolved once for everatproto/permission.md: an expiry of about 90 days90 days
reads a set hosted on its own accounts from its store, with no proofatproto/lexicon.md: resolution is authenticatedresolves it as any other, with its proof
fails a whole set when one permission has a field whose value is an objectatproto/permission.md: such a permission is ignoredthe same, as the reference: the harness compares the PAR's answer
drops a set's space permissions, as it serves no spacesspaces/proposal.md, "Permission sets": a set may grant themgrants them, as the pinned spaces alpha does (SPACES.md), against which the spaces run checks them (below)

And these, which the specs leave open and the server does as the reference does:

  • a permission with inheritAud: false is dropped;
  • the namespace is compared case and all, where atproto/nsid.md reads an authority without regard to case;
  • an expansion keeps duplicates, and the include expansions come before the scope's other tokens;
  • an include: that does not parse is dropped, not refused.

Environment

VariableIs
PDS_LEXICON_AUTHORITY_DIDoptional: a DID that is every NSID's authority, in place of DNS (above). One that is not a DID makes pds serve exit 1, with why on standard error

How it is checked

harness/checks/permission-sets.mjs. The harness runs a third PDS, a TestPds sharing the PLC directory, with one account that publishes the harness's sets as com.atproto.lexicon.schema records; the server is started with PDS_LEXICON_AUTHORITY_DID its DID, and the reference given the same setting (its lexicon.didAuthority), so both fetch each set over the network, with its proof. Each set has an NSID of its own, and none changes during a run. The sets: one with every kind of permission a set may grant, titles and details in more than one language, and inheritAud; one whose permissions are each dropped for one reason above; one with none kept; a document that is not a set; a document whose id is not its NSID; a set with a bad language key; and an NSID with no record.

Compared with the reference: PAR's answers for clients declaring each include: (with and without aud, and malformed); the page's __authorizeData, permissionSets among it; full sign-ins, with consent keeping or dropping each include:, and the token answers' scope; a refresh's scope; and the calls of OAUTH-SCOPES.md's steps made with such a session, allowed or refused as the reference allows or refuses them. The pages run (OAUTH-PAGES.md) draws clients with sets too. No set these compare grants a space permission, as the reference drops them; one the pages run shows on the server alone does (OAUTH-PAGES.md, "How it is checked").

A set's space permissions are checked in the spaces run (harness/spaces/scopes.mjs, SPACES.md), against the pinned spaces alpha: the run's lexicon authority publishes, beside its space type declarations, sets granting space permissions: a bare type, managing every authority, a key and actions, collections of another namespace and *, a type with no collections declared, and a type with no document; and permissions dropped, each for one reason above: spaceType *, a type of another namespace, a value the table does not allow, a field space does not take, a string for an array, an array for a string, and an empty array. Clients ask for them alone, with aud, beside space: and repo: tokens of their own, and twice. Compared: PAR's answer, the page's, the sign-in's and the token answer's scope, and each space method's answer to the session, as for a space: token (OAUTH-SCOPES.md, "How it is checked").

Held to this page, the server alone: a PDS_LEXICON_AUTHORITY_DID that is not a DID.

Not checked: the DNS lookup, which the harness cannot serve both sides (the server's own tests resolve _lexicon records from a stub DNS server); the caching times, as the harness does not wait an hour; a set changed during a session.