Decouple CAIP-27 from CAIP-25 and introduce CAIP-217 for Authorization Scopes

CAIPs/caip-171.md

@@ -50,12 +50,13 @@ type SessionIdentifier = string;
 
 Properties of the `SessionIdentifier` are as follows:
 1. It MUST uniquely identify an open and stateful session. 
-2. It MUST identify a closeable session, and it MUST become invalid
-   after a session is closed.
+2. It MUST identify a closeable session, and it MUST become invalid after a
+   session is closed.
 3. It MUST remain the same as the identified session's state changes.
-4. It MUST be serializable into JSON. Serialization and later deserialization using
-JSON MUST result in the same value.
-5. It MUST be generated from a cryptographically random source and MUST include at least 96 bits of entropy for security.
+4. It MUST be serializable into JSON. Serialization and later deserialization
+using JSON MUST result in the same value.
+5. It MUST be generated from a cryptographically random source and include at
+   least 96 bits of entropy for security.
 
 ## Copyright
 

CAIPs/caip-211.md

@@ -0,0 +1,263 @@
+---
+caip: 211
+title: JSON-RPC Authority Negotiation
+author: Hassan Malik (@hmalik88), Juan Caballero (@bumblefudge)
+discussions-to: ["https://github.com/ChainAgnostic/CAIPs/pull/207", "https://github.com/ChainAgnostic/CAIPs/pull/211"]
+status: Draft
+type: Informational
+created: 2023-02-02
+updated: 2023-02-02
+requires: [2, 10, 25, 171]
+---
+
+## Simple Summary
+
+CAIP-211 defines the behavior and semantics for both implicit and explicit RPC
+documents (which define methods and notifications for a given namespace or scope
+within one) and RPC endpoints (i.e. preferential routing for specific nodes). 
+
+## Abstract
+
+Without a profile of this CAIP which defines implicit values for a given
+namespace, setting the `rpcDocuments` and `rpcEndpoints` values in the
+`scopeObject`s of a [CAIP-25][] negotiation could be seen as a security risk
+within that namespace, since either a custom endpoint or a custom re-definition
+of a common method or event syntax or semantics would be harder for the
+respondent to detect. Once those implicit values have been profiled and
+published, however, the meaning of any explicit values in [CAIP-25][]
+negotiations or other scope expressions have an explicit baseline making RPC
+security postures more deterministic.
+
+## Motivation
+
+This deterministic expression of variations in RPC routing and behavior is a
+precondition for explicit and informed user consent to be gotten about these
+variations, in addition to supporting clarity between the multiple agents
+connecting that consenting user to a network. This enables flexible and layered mechanism for
+negotiating authorities over routing and RPC method/notification definitions. In
+turn, this allows experimentation and extension within certain local contexts
+(like a specific network within a namespace, or a specific community of usage of
+a network) without compromising the integrity and security of the broader
+community.
+
+## Specification
+
+### Implicit values
+
+Many namespaces have a single, authoritative RPC definition (whether
+human-readable, machine-readable, or both) and a set of endpoints which can be
+considered definitive. Where these can be referred to by a static URI and this
+URI is described in a [namespace profile][namespaces] of this CAIP, these static
+URIs are the "implicit" endpoint and document values for those namespaces.
+
+For a given namespace `X`, if the implicit RPC endpoints are `Y1`, `Y2` and
+`Y3`, and the implicit RPC document is `Z`, then the scope object
+
+```jsonc
+{
+  "X": {
+    methods: [A, B, C],
+    notifications: [D, E, F]
+  }
+}
+```
+
+SHOULD be interpreted as equivalent to the scope object: 
+
+```jsonc
+{
+  "X": {
+    methods: [A, B, C],
+    notifications: [D, E, F],
+    rpcEndpoints: [Y1, Y2, Y3],
+    rpcDocuments: [Z]
+  }
+}
+```
+
+### Explicit values
+
+Additional values may be set for a given `scopeObject`. 
+
+### Ordering 
+
+In the case of `rpcEndpoints`, priority is contextual and not defined
+universally. In the case of `rpcDocuments`, priority is more definitive: each
+document after the first MUST only add (and MUST NOT re-define) any terms
+already defined, iteratively through the array.
+
+For this reason, if a namespace has defined stable URIs for default
+`rpcDocuments` and `rpcEndpoints`, these SHOULD be defined in a namespace
+profile. These implicit values allow extensions and variations from those
+defaults to be negotiated, such as by [CAIP-25][] or other discovery protocols.
+
+In the context of a CAIP-25 negotiation, a requesting party may define explicit
+values for `rpcEndpoints` or `rpcDocuments` without including the implicit
+values. Extending the example above, we could say that the request:
+
+```jsonc
+{
+  "X": {
+    methods: [A, B, C],
+    notifications: [D, E, F],
+    rpcEndpoints: [U1, U2, U3],
+    rpcDocuments: [V]
+  }
+}
+```
+MUST be interpreted as replacing rather than appending to the implicit values.
+It MUST NOT be interpreted as equivalent to:
+
+```jsonc
+{
+  "X": {
+    methods: [A, B, C],
+    notifications: [D, E, F],
+    rpcEndpoints: [Y1, Y2, Y3, U1, U2, U3],
+    rpcDocuments: [Z, V]
+  }
+}
+```
+
+## Security Considerations
+
+The main security risk in accepting multiple authorities (expressed as URIs,
+which may be mutable) is that ambiguity and undesired behavior can arise from
+multiple RPC documents defining the same term, or different endpoints producing
+different outcomes. The solution to this is to assign priority by array ordering
+in the context of negotiation. In a protocol like [CAIP-25][], this means
+achieving consensus between parties on the exact priority before initiating a
+session.
+
+### CAIP-25 Example
+
+Since [CAIP-25][] obligates both parties in an authorization negotiation to
+persist and honor whatever `scopeObject`s they agree to, including the ordering
+of arrays, it is important to resolve all implicit and explicit members at the
+same negotiation step where `requiredScopes` and `optionalScopes` get merged
+into the `sessionScopes` both parties will persist. We can illustrate this
+resolution and all the possibilities open to a respondent by extending the
+examples above, in which a request omits implicit values Y1, Y2, Y3, and Z:
+
+```jsonc
+{
+  "requiredScopes": {
+    "X": {
+      methods: [A, B, C],
+      notifications: [D, E, F],
+    }
+  },
+  "optionalScopes": {
+    "X": {
+      methods: [A, B, C],
+      notifications: [D, E, F],
+      rpcEndpoints: [U1, U2, U3],
+      rpcDocuments: [V]
+    }
+  },
+}
+```
+
+Since the ordering of arrays expresses authority or priority in case of
+conflicts, we can illustrate three different security postures, explained below:
+
+```jsonc
+
+// Security Posture 1: Implicit value prioritized, requested values treated as extensions
+{
+  ...
+  "sessionScopes": {
+    "X": {
+      methods: [A, B, C],
+      notifications: [D, E, F],
+      rpcEndpoints: [Y1, Y2, Y3, U1, U2, U3],
+      rpcDocuments: [Z, V]
+    }
+  }
+  ...
+}
+
+// Security Posture 2: Explicit prioritized, but implicit values preserved
+{
+  ...
+  "sessionScopes": {
+    "X": {
+      methods: [A, B, C],
+      notifications: [D, E, F],
+      rpcEndpoints: [U1, U2, U3, Y1, Y2, Y3],
+      rpcDocuments: [V, Z]
+    }
+  }
+  ...
+}
+
+//Security Posture 3: Requested values only, explicit deauthorization of implicit values.
+{
+  ...
+  "sessionScopes": {
+    "X": {
+      methods: [A, B, C],
+      notifications: [D, E, F],
+      rpcEndpoints: [Y1, Y2, Y3],
+      rpcDocuments: [Z]
+    }
+  }
+  ...
+}
+
+```
+
+Option 1 would be the overwhelmingly most common, since implicit values are
+essentially the baseline consensus of an entire namespace (i.e. its network-wide
+basic RPC vocabulary), and any possible conflict between this and an extension
+should be sandboxed by not allowing an extension to override baseline.
+
+Option 2 would likely be quite rare, as a respondent and/or its controlling
+end-user would have to have a lot of out-of-band trust in an extension or local
+authority to allow it to override systemwide defaults. This could be thought of
+as "advanced mode" or "high-trust mode", and likely only enabled for a subset of
+end-users, perhaps negotiated by progressive re-authorization over time.
+
+Similarly, Option 3 would only make sense in special cases with meaningful
+consent of an end-user that knows they are entering a special-case and familiar
+UX and security assumptions. It could be thought of as "developer mode" or
+"alternate network configuration", and would getting meaningful consent from
+the end-user.
+
+Note that these three options are not exhaustive, just illustrative, and many
+combinations are also possible, i.e. combining the `rpcDocuments` in Option 1
+with the  `rpcEndpoints` value in Option 2.
+
+## Privacy Considerations
+
+The trust model of custom RPC endpoints and/or definition documents is complex
+and reputation/discovery systems are still emerging on a per-chain basis in many
+ecosystems. For this reason, negotiation protocols like [CAIP-25][] are best
+constructive iteratively and progressively to avoid malicious dapps partially
+deanonymizing wallets by profiling their support for custom RPCs (e.g., by
+"overasking" upfront).  For this reason, as with the initial CAIP-25 exchange,
+discovery requests rejected due to user input, due to security policy, and due
+to non-support at the wallet software level should not be distinguished at the
+RPC level.
+
+## References
+
+- [CAIP-2][] - Chain ID Specification
+- [CAIP-10][] - Account ID Specification
+- [CAIP-25][] - JSON-RPC Provider Request
+- [CAIP-75][] - Blockchain Reference for the Hedera namespace
+- [CAIP-171][] - Session Identifier Specification
+
+[CAIP-2]: https://chainagnostic.org/CAIPs/caip-2
+[CAIP-10]: https://chainagnostic.org/CAIPs/caip-10
+[CAIP-25]: https://chainagnostic.org/CAIPs/caip-25
+[CAIP-75]: https://chainagnostic.org/CAIPs/caip-75
+[CAIP-104]: https://chainagnostic.org/CAIPs/caip-104
+[CAIP-171]: https://chainagnostic.org/CAIPs/caip-171
+[namespaces]: https://namespaces.chainagnostic.org
+[RFC3339]: https://datatracker.ietf.org/doc/html/rfc3339#section-5.6
+[CAIP-170]: https://chainagnostic.org/CAIPs/caip-170
+
+## Copyright
+
+Copyright and related rights waived via [CC0](../LICENSE).

CAIPs/caip-217.md

@@ -0,0 +1,104 @@
+---
+caip: 217
+title: Authorization Scopes
+author: Pedro Gomes (@pedrouid), Hassan Malik (@hmalik88), Juan Caballero (@bumblefudge)
+discussions-to: ["https://github.com/ChainAgnostic/CAIPs/discussions/217","https://github.com/ChainAgnostic/CAIPs/discussions/211"]
+status: Draft
+type: Standard
+created: 2022-11-09
+---
+
+## Simple Summary
+
+This CAIP defines a simple syntax for scopes of authorization between
+applications (e.g. dapps) and user-agents (e.g. "wallets" or signers). These are
+expressed as JSON objects as a building block across multiple protocols and
+mechanisms, for example:
+- A JSON-RPC protocol for persisting and synchronizing authorized sessions
+  ([CAIP-25][])
+- Routing individual RPC commands to an authorized network ([CAIP-27][])
+
+## Motivation
+
+The layering of today's cryptographic and decentralized systems favors
+loosely-coupled combinations of protocols (representated in the CAIPs model as
+[namespaces][]), instances or consensus-communities within those protocols
+(addressed in the CAIPs model as [CAIP-2][] URNs), and sets of supported RPC
+methods and notifications used in those namespaces. Bundling all of these into
+an object facilitates unambiguous authorization schemes, including progressive
+authorization patterns, feature discovery, authority negotiation (See
+[CAIP-211][]) and delegations.
+
+## Specification
+
+An authorization scope is represented in JSON as an object which is keyed to a
+string that expresses its target network and contains arrays of strings
+expressing the various capabilities authorized there. When embedded in any other
+JSON context (including the `params` of a JSON-RPC message), the object MUST be
+expressed as the value of a property named by the scope string. 
+
+### Language
+
+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
+"SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" written in
+uppercase in this document are to be interpreted as described in [RFC
+2119](https://www.ietf.org/rfc/rfc2119.txt)
+
+### Definition
+
+The syntax of a `scopeObject` is as follows:
+
+```jsonc
+
+
+[scopeString]: {
+   *scopes: [(chainId)+],
+   methods: [(method_name)+],
+   notifications: [(notification_name)+],
+   *accounts: [(account_id)+]
+   *rpcDocuments: [(rpcDocument)+],
+   *rpcEndpoints: [(rpcEndpoint)+]
+}
+```
+
+Where:
+
+- {`scopeString`} (conditional) = EITHER a namespace identifier string registered in the CASA [namespaces][] registry to authorize multiple chains with identical properties OR a single, valid [CAIP-2][] identifier, i.e., a specific `chain_id` within a namespace.
+- `scopes` (conditional) = An array of 0 or more [CAIP-2][] `chainId`s. For each
+  entry in `scopes`, all the other properties of the `scopeObject` apply, but in
+  some cases, such as when members of `accounts` are specific to 1 or more
+  chains in `scopes`, they may be ignored or filtered where inapplicable;
+  namespace-specific rules for organizing or interpreting properties in
+  multi-scope MAY be specified in a [namespace-specific profile][namespaces] of
+  this specification.
+  - This property MUST NOT be present if the object is already scoped to a single `chainId` in the string value above.
+  - This property MUST NOT be present if the scope is an entire [namespace][namespaces] in which `chainId`s are not defined.
+  - This property MAY be present if the scope is an entire [namespace][namespaces] in which `chainId`s are defined.
+- `methods` = An array of 0 or more JSON-RPC methods that an application can call on the agent and/or an agent can call on an application.
+- `notifications` = An array of 0 or more JSON-RPC notifications that an application send to or expect from the agent.
+- `accounts` (optional) = An array of 0 or more [CAIP-10][] identifiers, each valid within the scope of authorization.
+- `rpcDocuments` (optional) = An array of URIs that each dereference to an RPC document specifying methods and notifications applicable in this scope. 
+  - These are ordered from most authoritative to least, i.e. methods defined more than once by the union of entries should be defined by their earliest definition only.
+- `rpcEndpoints` (optional) = An array of URLs that each dereference to an RPC endpoints for routing requests within this scope. 
+  - These are ordered from most authoritative to least, i.e. priority SHOULD be given to endpoints in the order given, as per the CAIP-211 profile for that [namespace][namespaces], if one has been specified.
+
+Additional constraints MAY be imposed by the usage of `scopeObject`s in
+protocols such as [CAIP-25][], and specific [namespaces][] may have
+implicit values or validity constraints for these properties.
+
+Whenever another CAIP uses the name `scopeObject` and has this CAIP in the
+`required` front-matter property, it SHALL be interpreted as reference to this
+specification.
+
+## References
+
+[CAIP-10]: https://chainAgnostic.org/CAIPs/CAIP-10
+[CAIP-25]: https://chainAgnostic.org/CAIPs/CAIP-25
+[CAIP-27]: https://chainAgnostic.org/CAIPs/CAIP-27
+[CAIP-211]: https://chainAgnostic.org/CAIPs/CAIP-211
+[namespaces]: https://namespaces.chainAgnostic.org/
+
+## Copyright
+
+Copyright and related rights waived via
+[CC0](https://creativecommons.org/publicdomain/zero/1.0/).