ERC-5573: Sign-In with Ethereum Capabilities, ReCaps

Abstract #

EIP-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 delegate capabilities with a certain extensible scope mechanism to an authorized delegee. How a delegee authenticates against the target resource is out of scope for this specification and depends on the implementation of the target resource.

Motivation #

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 (EIP-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 to interact with a third-party service (resource service) on behalf of the authenticated Ethereum account. For example, a relying party might 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 delegee) 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) whereas SIWE ReCap follows an Object Capability-based approach.

Specification #

This specification has three different audiences:

• Web3 application developers that want to integrate ReCaps to authenticate with any protocols and APIs that support object capabilities.
• Protocol or API developers that want to learn how to define their own ReCaps.
• Wallet implementers that want to improve the UI for ReCaps.

Terms and Definitions #

• ReCap - A SIWE Message complying with this specification, i.e., containing at least one ReCap URI in the Resources section and the corresponding human-readable ReCap Statement appended to the SIWE statement.
• ReCap URI - A type of URI under a certain namespace that resolves to a ReCap Details Object.
• ReCap Details Object - A JSON object describing the actions and optionally the resources associated with a ReCap Capability under a certain namespace.
• Resource Service (RS) - The entity that is providing third-party services for the Ethereum account.
• SIWE Client (SC) - The entity initiating the SIWE authentication and ReCap flow.
• Relying Party (RP) - same as SC in the context of authentication.

Overview #

This specification defines the following:

• ReCap SIWE Extension
• ReCap Capability
  • ReCap URI Scheme
  • ReCap Details Object Schema
• ReCap Translation Algorithm
• ReCap Verification

ReCap SIWE Extension #

A ReCap is an EIP-4361 message following a specific format that allows an Ethereum account to delegate a set of ReCap Capabilities to a delegee through informed consent. Each ReCap Capability MUST be represented by an 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:

• The URI field MUST specify the intended delegee, e.g., https://example.com, did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK. It is expected that the RS authenticates the delegee before invoking an action for the ReCap Capability.
• The Issued At field MUST be used to specify the issuance date of the ReCap Capabilities.
• If present, the 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.
• If present, the 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 https://example.com to perform the following actions on my behalf: (1) example: read for any. (2) example: append, delete for my.resource.1. (3) example: append for my.resource.2, my.resource.3.

URI: https://example.com
Version: 1
Chain ID: 1
Nonce: n-0S6_WzA2Mj
Issued At: 2022-06-21T12:00:00.000Z
Resources:
- urn:recap:example:eyJkZWYiOlsicmVhZCJdLCJ0YXIiOnsibXkucmVzb3VyY2UuMSI6WyJhcHBlbmQiLCJkZWxldGUiXSwibXkucmVzb3VyY2UuMiI6WyJhcHBlbmQiXSwibXkucmVzb3VyY2UuMyI6WyJhcHBlbmQiXX19

ReCap Capability #

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 SWIE message as described in the previous chapter, e.g., URI, Issued At, Expiration Time, Not Before.

ReCap URI Scheme #

A ReCap URI starts with urn:recap: followed by the namespace discriminator, followed by : and the 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.

The following is a non-normative example of a ReCap Capability that uses the example namespace:

urn:recap:example:eyJkZWZhdWx0QWN0aW9ucyI6WyJyZWFkIl0sInRhcmdldGVkQWN0aW9ucyI6eyJteS5yZXNvdXJjZS4xIjpbImFwcGVuZCIsImRlbGV0ZSJdLCJteS5yZXNvdXJjZS4yIjpbImFwcGVuZCJdLCJteS5yZXNvdXJjZS4zIjpbImFwcGVuZCJdfX0

It is expected that RS implementers define their own namespace, e.g., urn:recap:service:.

ReCap Details Object Schema #

The ReCap Details Object denotes which actions on which resources the delegee is authorized to invoke on behalf of the delegee 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": {
    "def": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1
      },  
      "minItems": 1
    },  
    "tar": {
      "type": "object",
      "patternProperties": {
        "^.+$": {
          "type": "array",
          "items": {
            "type": "string",
            "minLength": 1
          },  
          "minItems": 1
        }   
      },  
      "additionalProperties": false,
      "minProperties": 1
    },  
    "ext": {
      "type": "object",
      "minProperties": 1
    }   
  },  
  "minProperties": 1,
  "additionalProperties": false,
  "dependentSchemas": {
    "ext": {
      "minProperties": 2
    }   
  }
}

A ReCap Details Object defines the following properties:

• def: (CONDITIONAL) If present, def MUST be a JSON array of string values with at least one entry where each value describes an action the delegee MAY invoke in the RS on behalf of the Ethereum account without tying the scope to a particular target.
• tar: (CONDITIONAL) If present, tar MUST be a JSON object with variable properties where each property is a JSON array of string values each describing an action the delegee MAY invoke in the RS on behalf of the Ethereum account on the target resource denoted by the property name.
• ext: (OPTIONAL) If present, ext MUST be a JSON object with variable properties.

The following is a non-normative example of a ReCap Capability Object with def, tar and ext:

{
   "def":[
      "read"
   ],
   "tar":{
      "my.resource.1":[
         "append",
         "delete"
      ],
      "my.resource.2":[
         "append"
      ],
      "my.resource.3":[
         "append"
      ]
   },
   "ext":{
       "parentCapability": "bafybeigk7ly3pog6uupxku3b6bubirr434ib6tfaymvox6gotaaaaaaaaa"
   }
}

In the example above, the delegee is authorized to perform the action read independent of any resource, append, delete on resource my.resource.1, append on resource my.resource.2 and append on my.resource.3. Note, the delegee 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.

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.

ReCap Translation Algorithm #

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 EIP-4361 for definition of input-statement
recap-preamble = "I further authorize " uri " to perform the following actions on my behalf:"
   ; see EIP-4361 for definition of uri
recap-statement-entry = "(" number ") " recap-namespace ": " 
                          recap-action *("," recap-action) "for"
                          ( "any" / ( recap-resource *(", " recap-resource) ) )
   ; see RFC8259 for definition of number
recap-namespace = string
   ; see RFC8259 for definition of string
recap-action = 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:

• Let uri be the uri field of the input SIWE message conforming to EIP-4361.
• Let recap-uris be a non-empty array of ReCap URIs, which represent the ReCap Capabilities that are to be encoded in the SIWE message, and which contain ReCap Details Objects which conform to the ReCap Details Object Schema.
• [Optional] Let statement be the statement field of the input SIWE message conforming to EIP-4361. Algorithm:
• Let recap-transformed-statement be an empty string value.
• If statement is present, do the following:
  • Append the value of the statement field of siwe to recap-transformed-statement.
  • Append a single space character " " to recap-transformed-statement.
• Append the following string to recap-transformed-statement: "I further authorize ".
• Append uri to recap-transformed-statement.
• Append the following string to recap-transformed-statement: " to perform the following actions on my behalf:".
• Let numbering be an integer starting with 1.
• For each entry in recap-uris (starting with the first entry), perform the following:
  • Let namespace be the namespace in the ReCap URI entry and let capDetails be the base64url-decoded ReCap Details Object of the ReCap URI entry.
  • Let defaultActions be the def JSON array in capDetails, where each value represents an action.
  • If defaultActions is present, do the following:
    • Let actions be the string concatenation of each action in the array with the delimiter ", ".
    • Append the string concatenation of " (", numbering, ")" to recap-transformed-statement.
    • Append namespace concatenated with ": " to recap-transformed-statement.
    • Append actions to recap-transformed-statement.
    • Append the string " for any." to recap-transformed-statement.
    • Increase numbering by 1.
  • Let targetedActions be the tar JSON object in capDetails, where each key-value pair represents the set of actions allowed for a target.
  • If targetedActions is present, do the following:
    • Let actionSets be an array of arrays of strings;
    • For each key-value pair in targetedActions, ordered alphabetically by key, append the string array value to actionSets.
    • For each array of strings actionSet in actionSets, do the following:
      • Sort the strings in actionSet alphabetically.
      • Let actions be the string concatenation of each action in the array with the delimiter ", ".
      • Let targets be the string concatenation of each key in targetedActions with the delimiter ", ", for those keys such that the associated value (or any permutation of that value) is identical to actionSet.
      • Append the string concatenation of " (", numbering, ")" to recap-transformed-statement.
      • Append namespace concatenated with ": " to recap-transformed-statement.
      • Append actions to recap-transformed-statement.
      • Append the string " for " to recap-transformed-statement.
      • Append targets to recap-transformed-statement.
      • Append the string " ." to recap-transformed-statement.
      • Increase numbering by 1.
• Return recap-transformed-statement.

ReCap Verification Algorithm #

The following algorithm or an algorithm that produces the same output MUST be performed to verify a SIWE ReCap.

Inputs:

• Let recap-siwe be the input SIWE message conforming to EIP-4361 and this EIP.
• Let siwe-signature be the output of signing recap-siwe, as defined in EIP-4361. Algorithm:
• Perform EIP-4361 signature verification with recap-siwe and siwe-signature as inputs.
• Let uri be the uri field of recap-siwe.
• Let recap-uris be an array of recap URIs taken in order from the resources field of recap-siwe, such that URIs which are not valid ReCap URIs are ignored.
• Let recap-transformed-statement be the result of performing the above ReCap Translation Algorithm with uri and recap-uris as input.
• Assert that the statement field of recap-siwe ends with recap-transformed-statement.

Implementer's Guide #

TBD

Web3 Application Implementers #

TBD

Wallet Implementers #

TBD

Protocol or API Implementers #

TBD

Rationale #

TBD

Security Considerations #

Resource service implementer's should not consider ReCaps as bearer tokens but instead require to authenticate the delegee in addition. The process of authenticating the delegee against the resource service is out of scope of this specification and can be done in various different ways.

Copyright #

Copyright and related rights waived via CC0.