ERC-4361, or Sign-In with Ethereum (SIWE), describes how Ethereum accounts authenticate with off-chain services. This proposal, known as ReCaps, describes a mechanism on top of SIWE to give informed consent to authorize a Relying Party to exercise certain scoped capabilities. How a Relying Party authenticates against the target resource is out of scope for this specification and depends on the implementation of the target resource.
SIWE ReCaps unlock integration of protocols and/or APIs for developers by reducing user friction, onchain state and increasing security by introducing informed consent and deterministic capability objects on top of Sign-In With Ethereum (ERC-4361).
While SIWE focuses on authenticating the Ethereum account against the service (relying party or SIWE client) initiating the SIWE flow, there is no canonical way for the authenticated Ethereum account to authorize a relying party to interact with a third-party service (resource service) on behalf of the Ethereum account. A relying party may want to interact with another service on behalf of the Ethereum account, for example a service that provides data storage for the Ethereum account. This specification introduces a mechanism that allows the service (or more generally a Relying Party) to combine authentication and authorization of such while preserving security and optimizing UX.
Note, this approach is a similar mechanism to combining OpenID Connect (SIWE auth) and OAuth2 (SIWE ReCap) where SIWE ReCap implements capabilities-based authorization on top of the authentication provided by SIWE.
This specification has three different audiences:
Resources section and the corresponding human-readable ReCap Statement appended to the SIWE statement.This specification defines the following:
A ReCap is an ERC-4361 message following a specific format that allows an Ethereum account to delegate a set of ReCap Capabilities to a Relying Party through informed consent. ReCap Capabilities MUST be represented by the final entry in the Resources array of the SIWE message that MUST deterministically translate the ReCap Capability in human-readable form to the statement field in the SIWE message using the ReCap Translation Algorithm.
The following SIWE message fields are used to further define (or limit) the scope of all ReCap Capabilities:
URI field MUST specify the intended Relying Party, e.g., https://example.com, did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK. It is expected that the RS authenticates the Relying Party before invoking an action for the ReCap Capability.Issued At field MUST be used to specify the issuance date of the ReCap Capabilities.Expiration Time field MUST be used as the expiration time of the ReCap Capabilities, i.e. the time at which the RS will no longer accept an invocation of the capabilities expressed in this form.Not Before field MUST be used as the time that has to expire before the RS starts accepting invocations of the capabilities expressed in the message.The following is a non-normative example of a SIWE message with the SIWE ReCap Extension:
example.com wants you to sign in with your Ethereum account:
0x0000000000000000000000000000000000000000
I further authorize the stated URI to perform the following actions on my behalf: (1) 'example': 'append', 'read' for 'https://example.com'. (2) 'other': 'action' for 'https://example.com'. (3) 'example': 'append', 'delete' for 'my:resource:uri.1'. (4) 'example': 'append' for 'my:resource:uri.2'. (5) 'example': 'append' for 'my:resource:uri.3'.
URI: did:key:example
Version: 1
Chain ID: 1
Nonce: mynonce1
Issued At: 2022-06-21T12:00:00.000Z
Resources:
- urn:recap:eyJhdHQiOnsiaHR0cHM6Ly9leGFtcGxlLmNvbSI6eyJleGFtcGxlL2FwcGVuZCI6W10sImV4YW1wbGUvcmVhZCI6W10sIm90aGVyL2FjdGlvbiI6W119LCJteTpyZXNvdXJjZTp1cmkuMSI6eyJleGFtcGxlL2FwcGVuZCI6W10sImV4YW1wbGUvZGVsZXRlIjpbXX0sIm15OnJlc291cmNlOnVyaS4yIjp7ImV4YW1wbGUvYXBwZW5kIjpbXX0sIm15OnJlc291cmNlOnVyaS4zIjp7ImV4YW1wbGUvYXBwZW5kIjpbXX19LCJwcmYiOltdfQ
A ReCap Capability is identified by their ReCap URI that resolves to a ReCap Details Object which defines the associated actions and optional target resources. The scope of each ReCap Capability is attenuated by common fields in the SIWE message as described in the previous chapter, e.g., URI, Issued At, Expiration Time, Not Before.
A ReCap URI starts with urn:recap: followed by the unpadded base64url-encoded payload of the ReCap Details Object. Note, the term base64url is defined in RFC4648 - Base 64 Encoding with URL and Filename Safe Alphabet. If present, a Recap URI MUST occupy the final entry of the SIWE resource list.
The following is a non-normative example of a ReCap Capability:
urn:recap:eyJhdHQiOnsiaHR0cHM6Ly9leGFtcGxlLmNvbS9waWN0dXJlcy8iOnsiY3J1ZC9kZWxldGUiOlt7fV0sImNydWQvdXBkYXRlIjpbe31dLCJvdGhlci9hY3Rpb24iOlt7fV19LCJtYWlsdG86dXNlcm5hbWVAZXhhbXBsZS5jb20iOnsibXNnL3JlY2VpdmUiOlt7Im1heF9jb3VudCI6NSwidGVtcGxhdGVzIjpbIm5ld3NsZXR0ZXIiLCJtYXJrZXRpbmciXX1dLCJtc2cvc2VuZCI6W3sidG8iOiJzb21lb25lQGVtYWlsLmNvbSJ9LHsidG8iOiJqb2VAZW1haWwuY29tIn1dfX0sInByZiI6WyJ6ZGo3V2o2Rk5TNHJVVWJzaUp2amp4Y3NOcVpkRENTaVlSOHNLUVhmb1BmcFNadUF3Il19
Ability Strings identify an action or Ability within a Namespace. They are serialized as <namespace>/<ability>. Namespaces and Abilities MUST contain only alphanumeric characters as well as the characters ., *, _, +, -, conforming to the regex ^[a-zA-Z0-9.*_+-]$. The ability string as a whole MUST conform to ^[a-zA-Z0-9.*_+-]+\/[a-zA-z0-9.*_+-]+$. For example, crud/update has an ability-namespace of crud and an ability-name of update.
The ReCap Details Object denotes which actions on which resources the Relying Party is authorized to invoke on behalf of the Ethereum account for the validity period defined in the SIWE message. It can also contain additional information that the RS may require to verify a capability invocation. A ReCap Details Object MUST follow the following JSON Schema:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"att": {
"type": "object",
"propertyNames": {
"format": "uri"
},
"patternProperties": {
"^.+:.*$": {
"type": "object",
"patternProperties": {
"^[a-zA-Z0-9.*_+-]+\/[a-zA-z0-9.*_+-]+$": {
"type": "array",
"items": {
"type": "object"
}
}
},
"additionalProperties": false,
"minProperties": 1
}
},
"additionalProperties": false,
"minProperties": 1
},
"prf": {
"type": "array",
"items": {
"type": "string",
"format": "CID"
},
"minItems": 1
}
}
}
A ReCap Details Object defines the following properties:
att: (CONDITIONAL) If present, att MUST be a JSON object where each key is a URI and each value is an object containing Ability Strings as keys and a corresponding value which is an array of qualifications to the action (i.e. a restriction or requirement). The keys of the object MUST be ordered lexicographically.prf: (CONDITIONAL) If present, prf MUST be a JSON array of string values with at least one entry where each value is a valid Base58-encoded CID which identifies a parent capability, authorizing the Ethereum account for one or more of the entries in att if the SIWE address does not identify the controller of the att entries.Objects in the att field (including nested objects) MUST NOT contain duplicate keys and MUST have their keys ordered lexicographically with two steps:
msg/send comes before msg/send-to)This is the same as the Array.sort() method in JavaScript. In the example below, crud/delete must appear before crud/update and other/action, similarly msg/receive must appear before msg/send.
The following is a non-normative example of a ReCap Capability Object with att and prf:
{
"att":{
"https://example.com/pictures/":{
"crud/delete": [{}],
"crud/update": [{}],
"other/action": [{}]
},
"mailto:username@example.com":{
"msg/receive": [{
"max_count": 5,
"templates": ["newsletter", "marketing"]
}],
"msg/send": [{ "to": "someone@email.com" }, { "to": "joe@email.com" }]
}
},
"prf":["bafybeigk7ly3pog6uupxku3b6bubirr434ib6tfaymvox6gotaaaaaaaaa"]
}
In the example above, the Relying Party is authorized to perform the actions crud/update, crud/delete and other/action on resource https://example.com/pictures/ without limitations for any. Additionally the Relying Party is authorized to perform actions msg/send and msg/recieve on resource mailto:username@example.com, where msg/send is limited to sending to someone@email.com or joe@email.com and msg/recieve is limited to a maximum of 5 and templates newsletter or marketing. Note, the Relying Party can invoke each action individually and independently from each other in the RS. Additionally the ReCap Capability Object contains some additional information that the RS will need during verification. The responsibility for defining the structure and semantics of this data lies with the RS. These action and restriction semantics are examples not intended to be universally understood. The Nota Bene objects appearing in the array associated with ability strings represent restrictions on use of an ability. An empty object implies that the action can be performed with no restrictions, but an empty array with no objects implies that there is no way to use this ability in a valid way.
It is expected that RS implementers define which resources they want to expose through ReCap Details Objects and which actions they want to allow users to invoke on them.
This example is expected to transform into the following recap-transformed-statement (for URI of https://example.com):
I further authorize the stated URI to perform the following actions on my behalf: (1) 'crud': 'delete', 'update' for 'https://example.com/pictures/'. (2) 'other': 'action' for 'https://example.com/pictures/'. (3) 'msg': 'receive', 'send' for 'mailto:username@example.com'.
This example is also expected to transform into the following recap-uri:
urn:recap:eyJhdHQiOnsiaHR0cHM6Ly9leGFtcGxlLmNvbS9waWN0dXJlcy8iOnsiY3J1ZC9kZWxldGUiOlt7fV0sImNydWQvdXBkYXRlIjpbe31dLCJvdGhlci9hY3Rpb24iOlt7fV19LCJtYWlsdG86dXNlcm5hbWVAZXhhbXBsZS5jb20iOnsibXNnL3JlY2VpdmUiOlt7Im1heF9jb3VudCI6NSwidGVtcGxhdGVzIjpbIm5ld3NsZXR0ZXIiLCJtYXJrZXRpbmciXX1dLCJtc2cvc2VuZCI6W3sidG8iOiJzb21lb25lQGVtYWlsLmNvbSJ9LHsidG8iOiJqb2VAZW1haWwuY29tIn1dfX0sInByZiI6WyJ6ZGo3V2o2Rk5TNHJVVWJzaUp2amp4Y3NOcVpkRENTaVlSOHNLUVhmb1BmcFNadUF3Il19
Any two Recap objects can be merged together by recursive concatenation of their field elements as long as the ordering rules of the field contents is followed. For example, two recap objects:
{
"att": {
"https://example1.com": {
"crud/read": [{}]
}
},
"prf": ["bafyexample1"]
}
{
"att": {
"https://example1.com": {
"crud/update": [{
"max_times": 1
}]
},
"https://example2.com": {
"crud/delete": [{}]
}
},
"prf": ["bafyexample2"]
}
combine into:
{
"att": {
"https://example1.com": {
"crud/read": [{}],
"crud/update": [{
"max_times": 1
}]
},
"https://example2.com": {
"crud/delete": [{}]
}
},
"prf": ["bafyexample1", "bafyexample2"]
}
After applying the ReCap Translation Algorithm on a given SIWE message that MAY include a pre-defined statement, the recap-transformed-statement in a ReCap SIWE message MUST conform to the following ABNF:
recap-transformed-statement = statement recap-preamble 1*(" " recap-statement-entry ".")
; see ERC-4361 for definition of input-statement
recap-preamble = "I further authorize the stated URI to perform the following actions on my behalf:"
recap-statement-entry = "(" number ") " action-namespace ": "
action-name *("," action-name) "for"
recap-resource
; see RFC8259 for definition of number
ability-namespace = string
; see RFC8259 for definition of string
ability-name = string
; see RFC8259 for definition of string
recap-resource = string
; see RFC8259 for definition of string
The following algorithm or an algorithm that produces the same output MUST be performed to generate the SIWE ReCap Transformed Statement.
Inputs:
recap-uri be a ReCap URI, which represents the ReCap Capabilities that are to be encoded in the SIWE message, and which contains a ReCap Details Object which conforms to the ReCap Details Object Schema.statement be the statement field of the input SIWE message conforming to ERC-4361.
Algorithm:recap-transformed-statement be an empty string value.statement is present, do the following:statement field of siwe to recap-transformed-statement." " to recap-transformed-statement.recap-transformed-statement: "I further authorize the stated URI to perform the following actions on my behalf:".numbering be an integer starting with 1.attenuations be the att field of the ReCap Details Objectattenuations (starting with the first entry), perform the following:resource be the key and abilities be the valueabilities object by their ability-namespaceability-namespace, perform the following:" (", numbering, ")" to recap-transformed-statement.', ability-namespace, ': to recap-transformed-statement.ability-name in the ability-namespace group, perform the following:', ability-name, ' to recap-transformed-statementability-name, append , to recap-transformed-statementfor ', resource, '. to recap-transformed-statementnumbering by 1recap-transformed-statement.The following algorithm or an algorithm that produces the same output MUST be performed to verify a SIWE ReCap.
Inputs:
recap-siwe be the input SIWE message conforming to ERC-4361 and this EIP.siwe-signature be the output of signing recap-siwe, as defined in ERC-4361.
Algorithm:recap-siwe and siwe-signature as inputs.uri be the uri field of recap-siwe.recap-uri be a recap URI taken from the last entry of the resources field of recap-siwe.recap-transformed-statement be the result of performing the above ReCap Translation Algorithm with uri and recap-uri as input.recap-siwe ends with recap-transformed-statement.TBD
TBD
TBD
TBD
TBD
Resource service implementer's should not consider ReCaps as bearer tokens but instead require to authenticate the Relying Party in addition. The process of authenticating the Relying Party against the resource service is out of scope of this specification and can be done in various different ways.
Copyright and related rights waived via CC0.