chadtmiller.com/monolith
An atproto PDS
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.
| File | Is | Licence |
|---|---|---|
atproto/permission.md | permissions, the include resource, permission sets, their namespace authority, resolution and caching | CC-BY, atproto/LICENSE.txt |
atproto/lexicon.md | the permission-set and permission types; Lexicon publication and resolution | CC-BY, atproto/LICENSE.txt |
atproto/nsid.md | an NSID's authority and name | CC-BY, atproto/LICENSE.txt |
spaces/proposal.md | space 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:
-
The authority's DID. The NSID's authority is its segments but the last, reversed:
com.example.calendar.basePermissionshas the authoritycalendar.example.com. The server looks up the DNS TXT records of_lexicon.<authority>, and takes the one whose text beginsdid=, 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_DIDset 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.
-
The DID's document, as the server resolves any account's (
IDENTITY.md): its#atprotokey and its#atproto_pdsservice endpoint. Without either, the set does not resolve. -
The record.
GET <endpoint>/xrpc/com.atproto.sync.getRecordwithdid,collection=com.atproto.lexicon.schemaandrkey=<the NSID>, under the rules of the server's other outbound requests (PROXY.md: SSRF protection unlessPDS_DISABLE_SSRF_PROTECTION=true, no redirects followed), within 10 seconds, its answer at most 1 MiB. Anything but200with a CAR file, and the set does not resolve. -
Its proof, as
atproto/sync.mdhas a consumer check one: the CAR's root is a commit whosedidis the DID and whose signature the document's#atprotokey verifies, and the commit's MST holdscom.atproto.lexicon.schema/<the NSID>at a CID whose block, in the CAR, hashes to it. Anything else, and the set does not resolve. -
The document, the record's value:
$typecom.atproto.lexicon.schema,lexicon1,idthe NSID, anddefsan object with amainobject; else the set does not resolve;defs.main.typepermission-set; else it is not a set;permissionsan array of objects, each withtype: "permission"and aresourcestring, and every field of each a string, a number, a boolean, or an array of those;titleanddetail, if given, strings;title:langanddetail:lang, if given, objects whose keys are language tags (atproto/lexicon.md,languageformat) 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
resourceis notrepo,rpcorspace(blob,accountandidentitypermissions 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) andaction(an array ofcreate,update,delete); forrpc,lxm(required, an array of one or more NSIDs),audandinheritAud; forspace, the parameters ofOAUTH-SCOPES.md("Spaces", "Which parse"):spaceType(required),authorityandskey, each a string, andcollection,actionandmanage, each an array of one or more strings; - a field's value is not as above, or as that table allows for a
spacepermission; or arepocollection or anrpcmethod is*; - an
rpcpermission'saudis anything but*; inheritAudis anything buttrue; or it istrueand the permission has anaudtoo, or theinclude:has noaud. WithinheritAud: true, noaudand aninclude:aud, the permission's audience is theinclude:'s;- an
rpcpermission has neither anaudnorinheritAudwith aninclude:aud(anrpcpermission needs one audience); lxmis*andaudis*;- any of a
repopermission's collections or anrpcpermission's methods, or aspacepermission'sspaceType, 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 setcom.example.calendar.basePermissionsgrantscom.example.calendar.eventandcom.example.calendar.sub.thing, notcom.example.other.xnorcom.example.calendaritself. AspaceTypeof*is outside every namespace. Aspacepermission'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 afterrepo:(repo:com.example.post), several asrepo?collection=…with each in turn, sorted. Then the actions, after?(or&), each asaction=…in the order create, update, delete, each once; none written when the permission gives all three or none. An emptyactiondrops the permission.rpc: the methods, each once and sorted; one alone afterrpc:, several asrpc?lxm=…&lxm=…. Thenaud=<audience>, the audience percent-encoded but for letters, digits,-_.!~*'(),:and/: so#is written%23, and*,:and/are as they are.space: asOAUTH-SCOPES.mdwrites aspace:token again ("Spaces", "The token's scope"), from the permission's fields, their defaults left out:authorityselfandskey*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%23cal | rpc?lxm=com.example.calendar.addEvent&lxm=com.example.calendar.getEvents&aud=did:web:api.example.com%23cal |
space, spaceType: com.example.calendar.space | space: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 reference | The spec | The server |
|---|---|---|
| resolves a kept set again after 5 minutes | atproto/permission.md: a stale time no shorter than an access token's life | after an hour |
| keeps a set that resolved once for ever | atproto/permission.md: an expiry of about 90 days | 90 days |
| reads a set hosted on its own accounts from its store, with no proof | atproto/lexicon.md: resolution is authenticated | resolves it as any other, with its proof |
| fails a whole set when one permission has a field whose value is an object | atproto/permission.md: such a permission is ignored | the same, as the reference: the harness compares the PAR's answer |
drops a set's space permissions, as it serves no spaces | spaces/proposal.md, "Permission sets": a set may grant them | grants 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: falseis dropped; - the namespace is compared case and all, where
atproto/nsid.mdreads 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
| Variable | Is |
|---|---|
PDS_LEXICON_AUTHORITY_DID | optional: 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.