Implement CAIP-25 permission

[rekmarks]

Requires: #4239

For the Barad-dûr multichain milestone, we are implementing CAIP-25 handshakes. Consequently, our permission system needs to be able to express its granular authorization logic for RPC methods and notifications. After due consideration, we have decided that the solution is essentially to copypaste the CAIP-25 "scopes" object directly into permission controller state. This will require some means of hiding the permission controller's state shape from consumers (#4239). It will also facilitate the eventual removal of the RestrictedMethod permission type (#4238).

The CAIP-25 permission will consist of an endowment with a single caveat. The caveat's value will consist of a CAIP-25 scope object. This object is specified by CAIP-217. We will only permit a subset of the possible scope object shapes, elaborated below in TypeScript:

type Caip2Id = string; // e.g. eip155:1
type Caip10Id = `${Caip2Id}:${string}`; // e.g. eip155:1:0x1234...abcd

type Caip25CaveatValue = {
  [scope: Caip2Id]: {
    methods: string[], // method names
    notifications: string[], // notification names
    accounts: Caip10Id[],
  },
};

See CAIP-2 and CAIP-10 for the specifications of CAIP chain ids and account ids, respectively.

In particular, while we may accept any valid scope object at the API layer, our internal representation will require that every key is a complete CAIP-2 id. This is to say, we will pretend that scope objects of the form { [namespace]: { scopes: chainId[], ... } do not exist. Nor will we, at least at present, support any other scope object properties not listed in the above TypeScript definition, although we may add them in the future.

Since it trivially meets the needs of the multichain API, the CAIP-25 permission can also express any heretofore implemented RestrictedMethod. It also enables us to efficiently answer the question "can this dapp call this method?" by querying its caveat value. The existing permission middleware will have to be reimplemented to support this. In this manner, and alongside #4239, we can replace all existing restricted method implementations, and ship a multichain API.

Acceptance Criteria

• Implement a new endowment type permission that uses a caveat that contains the sessionScopes of CAIP-25 success response, but maintaining requiredScopes and optionalScopes metadata
• Implement the validation helper functions required to validate the caveat

[adonesky1]

Marking this as blocking https://app.zenhub.com/workspaces/wallet-api-platform-63bee08a4e3b9d001108416e/issues/gh/metamask/core/4239, since it will be easier to create an adapter once the permission exists

[vandan]

Hey team! Please add your planning poker estimate with Zenhub @adonesky1 @shanejonas @BelfordZ

[adonesky1]

Lets build off this branch: https://github.com/MetaMask/metamask-extension/pull/24181

[adonesky1]

list of metamask specific deviations from CAIP-25:

• Will not initially support requiredScopes, wildcard scopes, etc.