Add EIP-5573: SIWE ReCap Extension

EIPS/eip-5573.md

@@ -0,0 +1,271 @@
+---
+eip: 5573
+title: Sign-In with Ethereum Capabilities, CapGroks
+description: Mechanism on top of Sign-In with Ethereum for informed consent to delegate capabilities with an extensible scope mechanism
+author: Oliver Terbu (@awoie), Jacob Ward (@cobward), Charles Lehner (@clehner), Sam Gbafa (@skgbafa), Wayne Chang (@wyc)
+discussions-to: https://ethereum-magicians.org/t/eip-4362-siwe-capgrok/10627
+status: Draft
+type: Standards Track
+category: ERC
+created: 2021-07-20
+requires: 4361
+---
+
+## Abstract
+[EIP-4361](./eip-4361.md), or Sign-In with Ethereum (SIWE), describes how Ethereum accounts authenticate with off-chain services. This proposal, known as CapGroks, 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 CapGroks 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 CapGrok) whereas SIWE CapGrok follows an Object Capability-based approach.
+
+## Specification
+
+This specification has three different audiences:
+- Web3 application developers that want to integrate CapGroks to authenticate with any protocols and APIs that support object capabilities.
+- Protocol or API developers that want to learn how to define their own CapGroks.
+- Wallet implementers that want to improve the UI for CapGroks.
+
+### Terms and Definitions
+
+- CapGrok - A SIWE Message complying with this specification, i.e., containing at least one CapGrok URI in the `Resources` section and the corresponding human-readable CapGrok Statement appended to the SIWE `statement`.
+- CapGrok URI - A type of URI under a certain namespace that resolves to a CapGrok Details Object.
+- CapGrok Details Object - A JSON object describing the actions and optionally the resources associated with a CapGrok 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 CapGrok flow.
+- Relying Party (RP) - same as SC in the context of authentication.
+
+### Overview
+
+This specification defines the following:
+- CapGrok SIWE Extension
+- CapGrok Capability
+   - CapGrok URI Scheme
+   - CapGrok Details Object Schema
+- CapGrok Translation Algorithm
+- CapGrok Verification
+
+### CapGrok SIWE Extension
+
+A CapGrok is an EIP-4361 message following a specific format that allows an Ethereum account to delegate a set of CapGrok Capabilities to a delegee through informed consent. Each CapGrok Capability MUST be represented by an entry in the `Resources` array of the SIWE message that MUST deterministically translate the CapGrok Capability in human-readable form to the `statement` field in the SIWE message using the CapGrok Translation Algorithm.
+
+The following SIWE message fields are used to further define (or limit) the scope of all CapGrok 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 CapGrok Capability.
+- The `Issued At` field MUST be used to specify the issuance date of the CapGrok Capabilities.
+- If present, the `Expiration Time` field MUST be used as the expiration time of the CapGrok 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 CapGrok Extension:
+```text
+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:capability:example:eyJkZWYiOlsicmVhZCJdLCJ0YXIiOnsibXkucmVzb3VyY2UuMSI6WyJhcHBlbmQiLCJkZWxldGUiXSwibXkucmVzb3VyY2UuMiI6WyJhcHBlbmQiXSwibXkucmVzb3VyY2UuMyI6WyJhcHBlbmQiXX19
+```
+
+#### CapGrok Capability
+
+A CapGrok Capability is identified by their CapGrok URI that resolves to a CapGrok Details Object which defines the associated actions and optional target resources. The scope of each CapGrok 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`.
+
+##### CapGrok URI Scheme
+
+A CapGrok URI starts with `urn:capability:` followed by the namespace discriminator, followed by `:` and the base64url-encoded payload of the CapGrok 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 CapGrok Capability that uses the `example` namespace:
+```text
+urn:capability:example:eyJkZWZhdWx0QWN0aW9ucyI6WyJyZWFkIl0sInRhcmdldGVkQWN0aW9ucyI6eyJteS5yZXNvdXJjZS4xIjpbImFwcGVuZCIsImRlbGV0ZSJdLCJteS5yZXNvdXJjZS4yIjpbImFwcGVuZCJdLCJteS5yZXNvdXJjZS4zIjpbImFwcGVuZCJdfX0
+```
+
+It is expected that RS implementers define their own namespace, e.g., `urn:capability:service:`.
+
+##### CapGrok Details Object Schema
+
+The CapGrok 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 CapGrok Details Object MUST follow the following JSON Schema:
+
+```jsonc
+{
+  "$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 CapGrok 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 CapGrok Capability Object with `def`, `tar` and `ext`:
+```jsonc
+{
+   "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 invididually and independent from each other in the RS. Additionally the CapGrok 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 CapGrok Details Objects and which actions they want to allow to invoke on them.
+
+#### CapGrok Translation Algorithm
+
+After applying the CapGrok Translation Algorithm on a given SIWE message that MAY include a pre-defined `statement`, the `capgrok-transformed-statement` in a CapGrok SIWE message MUST conform to the following ABNF:
+```text
+capgrok-transformed-statement = statement capgrok-preamble 1*(" " capgrok-statement-entry ".")
+   ; see EIP-4361 for definition of input-statement
+capgrok-preamble = "I further authorize " uri " to perform the following actions on my behalf:"
+   ; see EIP-4361 for definition of uri
+capgrok-statement-entry = "(" number ") " capgrok-namespace ": " 
+                          capgrok-action *("," capgrok-action) "for"
+                          ( "any" / ( capgrok-resource *(", " capgrok-resource) ) )
+   ; see RFC8259 for definition of number
+capgrok-namespace = string
+   ; see RFC8259 for definition of string
+capgrok-action = string
+   ; see RFC8259 for definition of string
+capgrok-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 CapGrok Transformed Statement.
+
+Inputs:
+- Let `uri` be the uri field of the input SIWE message conforming to EIP-4361.
+- Let `capgrok-uris` be a non-empty array of CapGrok URIs, which represent the CapGrok Capabilities that are to be encoded in the SIWE message, and which contain CapGrok Details Objects which conform to the CapGrok Details Object Schema.
+- [Optional] Let `statement` be the statement field of the input SIWE message conforming to EIP-4361.
+Algorithm:
+- Let `capgrok-transformed-statement` be an empty string value.
+- If `statement` is present, do the following: 
+    - Append the value of the `statement` field of `siwe` to `capgrok-transformed-statement`.
+    - Append a single space character `" "` to `capgrok-transformed-statement`.
+- Append the following string to `capgrok-transformed-statement`: "I further authorize ".
+- Append `uri` to `capgrok-transformed-statement`.
+- Append the following string to `capgrok-transformed-statement`: " to perform the following actions on my behalf:".
+- Let `numbering` be an integer starting with 1.
+- For each entry in `capgrok-uris` (starting with the first entry), perform the following:
+  - Let `namespace` be the `namespace` in the CapGrok URI entry and let `capDetails` be the base64url-decoded CapGrok Details Object of the CapGrok 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 `capgrok-transformed-statement`.
+    - Append `namespace` concatenated with `": "` to `capgrok-transformed-statement`.
+    - Append `actions` to `capgrok-transformed-statement`.
+    - Append the string `" for any."` to `capgrok-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 `capgrok-transformed-statement`.
+      - Append `namespace` concatenated with `": "` to `capgrok-transformed-statement`.
+      - Append `actions` to `capgrok-transformed-statement`.
+      - Append the string `" for "` to `capgrok-transformed-statement`.
+      - Append `targets` to `capgrok-transformed-statement`.
+      - Append the string `" ."` to `capgrok-transformed-statement`.
+      - Increase `numbering` by 1.
+- Return `capgrok-transformed-statement`.
+
+#### CapGrok Verification
+
+The following algorithm or an algorithm that produces the same output MUST be performed to verify a SIWE CapGrok.
+
+Inputs:
+- Let `capgrok-siwe` be the input SIWE message conforming to EIP-4361 and this EIP.
+Algorithm:
+- Let `uri` be the uri field of `capgrok-siwe`.
+- Let `capgrok-uris` be an array of CapGrok URIs taken in order from the resources field of `capgrok-siwe`, such that URIs which are not valid CapGrok URIs are ignored.
+- Let `capgrok-transformed-statement` be the result of performing the above `CapGrok Translation Algorithm` with `uri` and `capgrok-uris` as input.
+- Assert that the statement field of `capgrok-siwe` ends with `capgrok-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 CapGroks 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](../LICENSE.md).