EIP-2255 Wallet permission system (Wallet Permissions System)

Final · Security & privacy · EIP status Final · created 2019-08-22

Adds two RPC methods, wallet_getPermissions and wallet_requestPermissions, to the wallet so that apps can request and check permission to use sensitive functionality in a standard way.

Why it is needed

A wallet mediates interaction between an untrusted app and a user's keys by obtaining the user's consent. Today's wallets pop up a confirmation dialog for every action. This preserves security but imposes a heavy burden on the user. In practice, many web3 apps send a chain of requests at the start of a session, such as disclosing the wallet address, switching networks, signing a cryptographic challenge, approving a token allowance, and sending a contract transaction. This proposal groups such requests into a human readable list of permissions, obtains consent for them all at once on the initial login screen, and requests additional permissions only when needed. This follows the same pattern as the OAuth2-style permission requests widely used on the web, so it is familiar to users. Users can also reject each permission individually or attenuate its conditions, for example by attaching an expiration date to a login or adjusting a token allowance amount themselves.

What changes

Today

After EIP-2255

Who is affected

In depth

wallet_getPermissions: querying current permissions

Called with no parameters and returns an array of Permission objects (the default is an empty array). A Permission consists of three fields: invoker, parentCapability, and caveats. The invoker is a URI identifying the origin of the requesting dapp (e.g. https://your-site.com/). The parentCapability is the name of the granted method (e.g. eth_accounts). The caveats are a list of constraints applied to that method, where each Caveat has a type (string) and a value (an arbitrary JSON value), and the meaning of the value is interpreted only within the context of its type.

wallet_requestPermissions: requesting permissions

Must take a single PermissionRequest object as its only parameter and must return an array of RequestedPermission objects. A PermissionRequest is a nested object keyed by methodName, holding a caveatName and a caveat value beneath it (e.g. requiredMethods: ["signTypedData_v3"] under eth_accounts). The returned RequestedPermission has a parentCapability and an optional date field, where date is the Unix timestamp of the request time. Calls to restricted methods must fail with an error until a wallet_requestPermissions request has been made and accepted by the user. If the request is rejected, an error with code 4001 must be thrown per EIP-1193.

Caveat: a constraint attached to a permission

A caveat is a specific restriction applied to a granted method. Users can not only approve or reject a permission wholesale but also attenuate its conditions. The source text gives two examples: a user adding an expiration date to a login request, and a user adjusting the amount directly in a token allowance request. Because a Caveat's type is a string and its value is an arbitrary JSON value, this open structure can express a wide variety of constraints.

Extensibility: specifying account capabilities

requestPermissions leaves room to be extended to include other options regarding the requested permission. For example, a site such as an exchange that requires signTypedData_v3 can specify that requirement, since some hardware wallets do not support this method. The wallet can then show only compatible accounts while still preserving the user's privacy and choice regarding how they store their keys. The test cases also include an example of requesting the eth_accounts permission with a requiredMethods: ['signTypedData_v3'] caveat attached.

Security considerations: SSRF

This consideration applies to the case of displaying a website's favicon. A wallet must be careful about sending requests to arbitrary URLs. It is recommended to sanitize URIs with a whitelist approach that allows only specific schemes and ports. A vulnerable wallet could, for example, be tricked into tampering with data in a locally running redis database. This EIP is an interface standard with status Final, adding two methods on top of the EIP-1193 provider API.

Original EIP · ← EIPs