ERC-5573 Sign-In with Ethereum Authorization Delegation, ReCap (Sign-In with Ethereum Capabilities, ReCaps)
Draft · Signatures & auth · created 2021-07-20
When logging in with an Ethereum account (SIWE), a single signature lets you explicitly delegate the scope of actions a service can take on behalf of your account with other services.
Why it is needed
The Sign-In with Ethereum standard (ERC-4361, SIWE) only defines how an Ethereum account authenticates itself to an off-chain service. However, after logging in, that service often needs to interact with third-party services on the user's behalf, for example accessing a storage service that holds the user's data. Until now there has been no standard way for an authenticated account to hand over such authorization to a service. As a result, authentication and authorization had to be handled separately, which added steps for the user and made it hard to know exactly what was being permitted. This proposal (ReCap) layers a human-readable consent statement and a machine-verifiable capability object on top of the SIWE signed message, enabling authorization delegation based on informed consent.
In depth
Extension Structure on Top of the SIWE Message
ReCap is a specific format of the ERC-4361 message. The ReCap Capability must be included as the last entry in the Resources array of the SIWE message, and its content must be deterministically converted into human-readable form in the statement field via the translation algorithm. Existing SIWE fields are used to bound the scope of the authorization. The URI field must specify the relying party to whom authorization is delegated (for example, https://example.com, did:key:...). Issued At is the time the authorization was issued; if Expiration Time is present, it is the time the authorization expires; if Not Before is present, the resource service accepts the exercise of the authorization only from that time onward.
ReCap URI Scheme
A ReCap URI takes the form of urn:recap: followed by the ReCap Details Object encoded as unpadded base64url. base64url is a Base 64 encoding that uses the URL- and filename-safe alphabet from RFC4648. If a ReCap URI is present, it must occupy the last entry in the SIWE resource list.
Ability String
An ability string identifies an action within a namespace and is serialized in the form <namespace>/<ability>. Namespace and ability names may use only alphanumeric characters and . * _ + -, and the full string must match the regular expression ^[a-zA-Z0-9.*_+-]+\/[a-zA-z0-9.*_+-]+$. For example, in crud/update, the namespace is crud and the ability name is update.
ReCap Details Object: att and prf
The att field is an object whose keys are resource URIs and whose values are objects keyed by ability string, with an array of restriction or qualification objects for that action as the value. Keys must be sorted lexicographically, sorted by byte value, with a shorter string coming before a string it is a prefix of (msg/send comes before msg/send-to). This is the same ordering as JavaScript's Array.sort(), and duplicate keys are forbidden. An empty object within the array means the action can be performed without restriction, while an empty array with no objects at all means there is no valid way to exercise that ability. The prf field is an array of Base58-encoded CID strings that point to the parent authorizations backing the permission when the SIWE address is not the controller of the att entry. Responsibility for defining the structure and meaning of restriction data rests with the resource service.
Merging Capability Objects
Two ReCap objects can be merged into one by recursively concatenating each field's elements, as long as the ordering rules for the field content are respected. For example, merging two objects that hold crud/read authorization and crud/update authorization for the same resource results in both abilities being included under that resource, and the prf array including entries from both sides.
Translation Algorithm: From Machine Capabilities to Human Sentences
The translation algorithm converts the att content inside a ReCap URI into a statement sentence. If an existing statement is present, a single space is appended after it, followed by the header "I further authorize the stated URI to perform the following actions on my behalf:", and then items numbered starting from (1) are appended, grouping ability strings by namespace for each resource. Other implementations are allowed as long as they produce the same output. This makes it possible to mechanically verify that the signed statement and the encoded authorization object always match.
Verification algorithm
The verifier first performs ERC-4361 signature verification. It must then run the translation algorithm with the message's uri field and the ReCap URI from the last entry in resources as input, and check that the message's statement ends with the resulting string. How the relying party authenticates itself to the resource service is outside the scope of this specification and is left to the resource service's implementation.
Still in draft stage
This proposal's status is Draft. The Rationale and Implementer's Guide sections of the original text are also still to be determined (TBD). Keep in mind that the content may change going forward.
Things to watch out for
- Not Treating ReCap as a Bearer Token: Resource service implementers must not treat a ReCap as a bearer token usable by anyone who holds it; they must additionally authenticate the relying party. The specific method for authenticating the relying party is outside the scope of this specification and can be done in various ways.