diff --git a/CAIPs/caip-25.md b/CAIPs/caip-25.md index aac22cd6..5c6b3e05 100644 --- a/CAIPs/caip-25.md +++ b/CAIPs/caip-25.md @@ -7,7 +7,7 @@ status: Review type: Standard created: 2020-10-14 updated: 2024-07-02 -requires: 2, 10, 171, 217 +requires: 2, 10, 171, 217, 285, 311, 312 --- ## Simple Summary @@ -25,11 +25,43 @@ The motivation comes from the lack of standardization across blockchains to expo ## Specification -The session is proposed by a caller and the response by the respondent is used as the baseline for an ongoing session that both parties will persist. -The properties and authorization scopes that make up the session are expected to be persisted and tracked over time by both parties in a discrete data store, identified by an entropic [identifier][CAIP-171] assigned in the initial response. -This object gets updated, extended, closed, etc. by successive calls and notifications, each tagged by this identifier. +### Language -If a respondent (e.g. a wallet) needs to initiate a new session, whether due to user input, security policy, or session expiry reasons, it can simply generate a new session identifier to signal this notification to the calling provider; if a caller needs to initiate a new session, it can do so by sending a new request without a `sessionIdentifier`. In such cases, a respondent (e.g. wallet) may choose to explicitly close all sessions upon generation of a new one from the same origin or identity, or leave it to time-out; maintaining concurrent sessions is discouraged (see Security Considerations). +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][] + +### Definition + +#### Session Lifecycle + +The session is proposed by a caller and the response by the respondent is used as the baseline for an ongoing session between the two parties. +- When a wallet responds with a success response containing a `sessionId` (an entropic [identifier][CAIP-171]), the properties and authorization scopes that make up the session should be persisted and tracked over the life of the session by both parties in a discrete data store. +- When the wallet does not provide a `sessionId` in its initial response, the wallet MUST persist and track the properties and authorization scopes that make up the session. +The caller is not expected to persist session data or even a `sessionId`. +Note that wallets NOT returning `sessionId`s MUST implement additional methods and notifications to handle the full lifecycle of the session: + * [`wallet_getSession`][CAIP-312] to enable the caller to query for the current status of the session at any time. + * [`wallet_revokeSession`][CAIP-285] to explicitly end the session + * [`wallet_sessionChanged`][CAIP-311] to notify caller of updated session authorizations. + +After a session is established between wallet and caller, subsequent `wallet_createSession` calls can be used to update the properties and authorization scopes of the session. +- When a `sessionId` is returned in the initial `wallet_createSession` response, subsequent `wallet_createSession` calls either: + - include a previously used `sessionId` on the root of the request meaning this request is intended to modify that session, or + - do not include a `sessionId`, in which case a new session is created - the respondent generates a new `sessionId` and sends it with the success response - and the previous session dangles in parallel (until its expiration, if applicable), though maintaining concurrent sessions is discouraged (see Security Considerations). +- When the wallet does not provide a `sessionId` in its initial response, subsequent `wallet_createSession` calls overwrite the previous singular session between caller and wallet. + +When a user wishes to update the authorizations of an active session from within the wallet, the wallet should notify the caller of the changes with a [`wallet_sessionChanged`][CAIP-311] notification. + +If a connection is initially established without a `sessionId` and the wallet later implements `sessionId` support, the wallet can revoke the single session and notify the caller via `wallet_sessionChanged`. When the caller seeks to re-establish the session via `wallet_createSession`, the wallet should return a `sessionId` in the response. + +When a caller wishes revoke an active session, it can do so by calling [`wallet_revokeSession`][CAIP-285]. +- When a `sessionId` is returned in the initial `wallet_createSession` response, the caller MUST call `wallet_revokeSession` with the supplied `sessionId` to revoke that session. +- When the wallet does not provide a `sessionId` in its initial response, a call to `wallet_revokeSession` revokes the single active session between caller and wallet. + +For more detail on the lifecycle and management of sessions with and without `sessionId`s, see the informational [CAIP-316][]. + +#### Session Data and Metadata Initial and ongoing authorization requests are grouped into two top-level arrays of [scopeObjects][CAIP-217], named `requiredScopes` and `optionalScopes` respectively. @@ -93,7 +125,7 @@ Example: "sessionProperties": { "expiry": "2022-12-24T17:07:31+00:00", "caip154-mandatory": "true" - } + } } } ``` @@ -116,8 +148,10 @@ similarly, the `requiredScopes`, `optionalScopes`, and `sessionScopes` arrays re The same absolute security posture is not expected for the metadata objects `scopedProperties` and `sessionProperties`, but caution is still recommended for such extensions: callers and respondents alike SHOULD allow for their counterparties dropping or ignoring unfamiliar members from either. -Requesting applications and respondents alike are expected to manage state for the connection, including `scopedProperties` and `sessionProperties`; -if multiple concurrent connections are allowed, callers are expected to maintain them segregated and identified by the unique `sessionId` returned initially. +When a `sessionId` is returned with the initial success response, requesting applications and respondents alike are expected to manage state for the connection, including `scopedProperties` and `sessionProperties`, and that same `sessionId` should be added to the `wallet_createSession` request to update the associated session. +When no `sessionId` is included in an initial success response, a caller does not need to maintain `sessionId` state and can assume the extension methods defined in [CAIP-311][] and [CAIP-312][] are available for refreshing and updating the session directly. +See [CAIP-316][] for more on lifecycle management. +if multiple concurrent connections are allowed, callers are expected to track, persist and identify them separately by the unique `sessionId` returned initially. ### Response @@ -125,10 +159,9 @@ The wallet can respond to this method with either a success result or an error m #### Success -The successful result contains one mandatory string (keyed as `sessionId` with a value conformant to [CAIP-171][]) and two session objects, both mandatory and non-empty. - -The first is called `sessionScopes` and contains 1 or more `scopeObjects`. +The successful result MAY contain a string (keyed as `sessionId` with a value conformant to [CAIP-171][]). As described above, if a `sessionId` is returned in the response, the caller should persist and track the properties and authorization scopes associated with this `sessionid`. If the wallet does not return a `sessionId` in the response, the connection will only consist of one session at a time, the contents of which are always retrievable for the caller via [`wallet_getSession`][CAIP-312]. +The successful result MUST contain an object called `sessionScopes` which contains 1 or more `scopeObjects`. - All required `scopeObjects` and all, none, or some of the optional `scopeObject`s (at the discretion of the provider) MUST be included if successful. - Unlike the request, each scope object MUST also contain an `accounts` array, containing 0 or more [CAIP-10][]-conformant accounts authorized for the session @@ -285,7 +318,7 @@ or feature-completeness information to a malicious or fingerprinting caller. ## Security Considerations The crucial security function of a shared session negotiated and maintained by a -series of CAIP-25 calls is to reduce ambiguity in authorization. This requires +series of CAIP-25 calls is to reduce ambiguity in authorization. This requires a potentially counterintuitive structuring of the building-blocks of a Chain-Agnostic session into scopes at the "namespace-wide" ([CAIP-104][]) or at the "chain-specific" ([CAIP-2][]) level; for this reason, requests and responses @@ -340,6 +373,7 @@ was in violation of policy). ## Changelog +-- 2024-07-29: added lifecycle management methods and notification for single session connections, see [CAIP-316][] for equivalence chart and diagrams - 2024-07-16: redefined requiredScopes to be functionally equivalent to optionalScopes, but semantically different; previously, authorizing less than 100% of reqScopes required rejecting the connection - 2023-03-29: refactored out scopeObject syntax as separate CAIP-217, simplified - 2022-11-26: add mandatory indexing by session identifier (i.e. CAIP-171 requirement) @@ -352,12 +386,20 @@ was in violation of policy). - [CAIP-104][] - Definition of Chain Agnostic Namespaces or CANs - [CAIP-171][] - Session Identifier, i.e. syntax and usage of `sessionId`s - [CAIP-217][] - Authorization Scopes, i.e. syntax for `scopeObject`s +- [CAIP-285][] - `wallet_revokeSession` Specification +- [CAIP-312][] - `wallet_getSession` Specification +- [CAIP-311][] - `wallet_sessionChanged` Specification +- [CAIP-316][] - Session Lifecycle Management equivalence chart and diagrams [CAIP-2]: https://chainagnostic.org/CAIPs/caip-2 [CAIP-10]: https://chainagnostic.org/CAIPs/caip-10 [CAIP-104]: https://chainagnostic.org/CAIPs/caip-104 [CAIP-171]: https://chainagnostic.org/CAIPs/caip-171 [CAIP-217]: https://chainagnostic.org/CAIPs/caip-217 +[CAIP-285]: https://chainagnostic.org/CAIPs/caip-285 +[CAIP-312]: https://chainagnostic.org/CAIPs/CAIP-312 +[CAIP-311]: https://chainagnostic.org/CAIPs/CAIP-311 +[CAIP-316]: https://chainagnostic.org/CAIPs/caip-316 [namespaces]: https://namespaces.chainagnostic.org [RFC3339]: https://datatracker.ietf.org/doc/html/rfc3339#section-5.6 diff --git a/CAIPs/caip-27.md b/CAIPs/caip-27.md index 8c84fcae..e3f596d6 100644 --- a/CAIPs/caip-27.md +++ b/CAIPs/caip-27.md @@ -103,7 +103,7 @@ three **required parameters**: ### Response -Upon succesful validation, the respondent will submit or route the request to +Upon successful validation, the respondent will submit or route the request to the targeted chain. If the targeted chain returns a response to the respondent, the respondent MAY forward this response to the caller. Constraints on, metadata about, or envelopes for response-forwarding MAY be set by diff --git a/CAIPs/caip-285.md b/CAIPs/caip-285.md new file mode 100644 index 00000000..79f71d9f --- /dev/null +++ b/CAIPs/caip-285.md @@ -0,0 +1,131 @@ +--- +caip: 285 +title: JSON-RPC Method for Revoking Session Authorizations +author: [Alex Donesky] (@adonesky1) +discussions-to: https://github.com/ChainAgnostic/CAIPs/pull/285/files +status: Draft +type: Standard +created: 2024-07-12 +requires: 25, 217 +--- + +## Simple Summary + +CAIP-285 introduces the `wallet_revokeSession` method for fully revoking the authorizations and properties of an active [CAIP-25][] session. + +## Abstract + +This proposal aims to enhance session management for [CAIP-25][] initiated sessions by defining a new JSON-RPC method for revoking sessions. This method provides an explicit protocol for revoking sessions with or without `sessionId`s. + +## Motivation + +The motivation behind this proposal is to enhance the flexibility of [CAIP-25][] initated sessions by enabling the revocation of session authorizations without `sessionId`s, which don't map well to extension-based wallet's dapp connections and could add unnecessary constraints and burdens to existing flows. The proposed method provides an intuitive way to revoke authorizations of an active session, simplifying the management of session lifecycles. + +## Specification + +### Definition + +The `wallet_revokeSession` method revokes the entire active session. +If a `sessionId` parameter is provided, it revokes that specific session only; +if no `sessionId` parameter is provided and there is an active session without a `sessionId` this session gets revoked and a success result is returned; +otherwise, an appropriate error message is sent. + +**Parameters:** + +- `sessionId` (string, optional): The session identifier. + +### Request + +The caller would interface with a wallet via the same channel by which it called `wallet_createSession` to revoke a session by calling the following JSON-RPC request: + +```jsonc +{ + "id": 1, + "jsonrpc": "2.0", + "method": "wallet_revokeSession", + "params": {} +} +``` + +### Response + +The wallet can respond to this method with either a success result or an error message. + +### Success + +Upon a successful `wallet_revokeSession` call a wallet should remove authorizations and session properties associated with the revoked session. + +An example of a successful response follows: + +```jsonc +{ + "id": 1, + "jsonrpc": "2.0", + "result": true +} +``` + +### Failure States + +The response MUST NOT be a JSON-RPC success result in any of the following failure states. + +#### Generic Failure Code + +Unless the dapp is known to the wallet and trusted, the generic/undefined error response: + +```jsonc +{ + "id": 1, + "jsonrpc": "2.0", + "error": { + "code": 0, + "message": "Unknown error" + } +} +``` + +is RECOMMENDED for any of the following cases: + +- a sessionId is passed but not recognized, +- no sessionId is passed and only active session(s) have sessionIds, or +- there are no active sessions + +#### Trusted Failure Codes + +More informative error messages MAY be sent in trusted-counterparty circumstances, although extending this trust too widely may contribute to widespread fingerprinting and analytics which corrode herd privacy (see Privacy Considerations below). The core error messages over trusted connections are as follows: + +The valid error message codes are the following: + +- When a sessionId is passed but not recognized: + + - code = 5500 + - message = "SessionId not recognized" + +- When there are no active sessions: + + - code = 5501 + - message = "No active sessions" + +- When no sessionId is passed and only active session(s) have sessionIds: + + - code = 5502 + - message = "All active sessions have sessionIds" + +## Security Considerations + +The introduction of this lifecycle method must ensure that only authorized parties can retrieve the authorizations of a session. Proper authentication and authorization mechanisms must be in place to prevent unauthorized access or modifications. + +To achieve this, it is recommended to establish a connection over domain-bound or other 1:1 transports. Where applicable, additional binding to a `sessionId` is recommended to ensure secure session management. This approach helps to create a secure communication channel that can effectively authenticate and authorize session-related requests, minimizing the risk of unauthorized access or session hijacking. + +## Links + +- [CAIP-25] - JSON-RPC Handshake Protocol Specification. i.e `wallet_createSession` +- [CAIP-217]- Authorization Scopes, i.e. syntax for `scopeObject`s + +[CAIP-25]: https://chainagnostic.org/CAIPs/caip-25 +[CAIP-217]: https://chainagnostic.org/CAIPs/caip-217 + +## Copyright + +Copyright and related rights waived via +[CC0](https://creativecommons.org/publicdomain/zero/1.0/). diff --git a/CAIPs/caip-311.md b/CAIPs/caip-311.md new file mode 100644 index 00000000..92f9edba --- /dev/null +++ b/CAIPs/caip-311.md @@ -0,0 +1,78 @@ +--- +caip: 311 +title: JSON-RPC Event for Session Authorization Updates +author: [Alex Donesky] (@adonesky1) +discussions-to: https://github.com/ChainAgnostic/CAIPs/pull/285/files +status: Draft +type: Standard +created: 2024-07-12 +requires: 25, 217 +--- + +## Simple Summary + +CAIP-311 introduces the `wallet_sessionChanged` event for notifying callers party to an active [CAIP-25][] session of updates to session authorizations made by users directly in the wallet. + +## Abstract + +This proposal aims to extend the [CAIP-25][] standard by defining a new JSON-RPC event for notifying the caller of updates to session authorizations. This event allows wallets to dynamically inform callers of changes to authorizations made by users on the wallet side, without having to initiate a new session each time. + +## Motivation + +The motivation behind this proposal is to provide bidirectional management of [CAIP-25][] session authorizations. The proposed event provides an intuitive way to notify dapps of changes to authorizations within an active session, simplifying the management of session lifecycles. + +## Definition + +## Specification + +This event is published by the wallet to notify the callers of updates to a shared session's authorization scopes. The event payload contains the new `sessionScopes`. If a connection between the wallet and the caller is severed and the possibility of missed events arises, the caller should immediately call `wallet_getSession` to retrieve the current session scopes. + +**Notification Parameters:** + +- `sessionId` (string, optional): The session identifier. +- `sessionScopes` (object of `scopeObject` objects, required): An object containing the full updated session scopes, each formatted according to [CAIP-217][]. + +**Notification:** + +```jsonc +{ + "method": "wallet_sessionChanged", + "params": { + "sessionScopes": { + "eip155:1": { + "methods": ["eth_signTransaction", "eth_sendTransaction"], + "notifications": ["accountsChanged"], + "accounts": ["eip155:1:0xabc123"] + }, + "eip155:137": { + "methods": ["eth_sendTransaction"], + "notifications": [], + "accounts": ["eip155:137:0xdef456"] + } + } + } +} +``` + +## Security Considerations + +The introduction of this lifecycle method must ensure that only authorized parties can retrieve the authorizations of a session. Proper authentication and authorization mechanisms must be in place to prevent unauthorized access or modifications. + +To achieve this, it is recommended to establish a connection over domain-bound or other 1:1 transports. Where applicable, additional binding to a `sessionId` is recommended to ensure secure session management. This approach helps to create a secure communication channel that can effectively authenticate and authorize session-related requests, minimizing the risk of unauthorized access or session hijacking. + +## Links + +- [CAIP-25] - JSON-RPC Handshake Protocol Specification. i.e `wallet_createSession` +- [CAIP-217]- Authorization Scopes, i.e. syntax for `scopeObject`s + +[CAIP-25]: https://chainagnostic.org/CAIPs/caip-25 +[CAIP-217]: https://chainagnostic.org/CAIPs/caip-217 +[CAIP-311]: https://chainagnostic.org/CAIPs/caip-311 +[CAIP-312]: https://chainagnostic.org/CAIPs/caip-312 +[CAIP-316]: https://chainagnostic.org/CAIPs/caip-316 + + +## Copyright + +Copyright and related rights waived via +[CC0](https://creativecommons.org/publicdomain/zero/1.0/). diff --git a/CAIPs/caip-312.md b/CAIPs/caip-312.md new file mode 100644 index 00000000..df870843 --- /dev/null +++ b/CAIPs/caip-312.md @@ -0,0 +1,121 @@ +--- +caip: 312 +title: JSON-RPC Method for Retrieving Session Authorizations +author: [Alex Donesky] (@adonesky1) +discussions-to: https://github.com/ChainAgnostic/CAIPs/pull/285/files +status: Draft +type: Standard +created: 2024-07-13 +requires: 25, 217 +--- + +## Simple Summary + +CAIP-312 introduces the `wallet_getSession` method for retrieving authorizations from an active [CAIP-25][] initiated session. + +## Abstract + +This proposal aims to extend the [CAIP-25][] standard by defining a new JSON-RPC method for retrieving authorizations within a session. This method allows callers to dynamically retrieve authorizations and properties. + +## Motivation + +The motivation behind this proposal is to enhance the flexibility of [CAIP-25][] by enabling the retrieval of session authorizations at any time. The proposed method provides an intuitive way to retrieve authorizations for an active session, allowing callers to access session data without having to persist and track it over the full life of the method. + +## Specification + +### Definition + +The `wallet_getSession` method returns an active session. +If a `sessionId` is provided, it returns the authorizations for that specific session; +If no `sessionId` parameter is provided - and there is a single active session with no `sessionId` assigned - it returns the session authorizations and properties for that session; +otherwise, an appropriate error message; + +**Parameters:** + +- `sessionId` (string, optional): The session identifier. + +### Request + +The caller would interface with a wallet via the same provider by which it called `wallet_createSession` to retrieve a session by calling the following JSON-RPC request: + +```jsonc +{ + "id": 1, + "jsonrpc": "2.0", + "method": "wallet_getSession", + "params": {} +} +``` + +### Response + +An example of a successful response follows: + +```jsonc +{ + "id": 1, + "jsonrpc": "2.0", + "result": { + "sessionScopes": { + "eip155:1": { + "methods": ["eth_signTransaction"], + "notifications": ["accountsChanged"], + "accounts": ["eip155:1:0xabc123"] + }, + "eip155:137": { + "methods": ["eth_sendTransaction"], + "notifications": ["chainChanged"], + "accounts": ["eip155:137:0xdef456"] + }, + "solana:4sGjMW1sUnHzSxGspuhpqLDx6wiyjNtZ": { + "methods": ["getBalance", "getAccountInfo", "sendTransaction", "getBlock"], + "notifications": [], + "accounts": ["solana:4sGjMW1sUnHzSxGspuhpqLDx6wiyjNtZ:4Nd1mS8AUwK3kU3gdiAM6QCvqhA7Do8rKtMXsGyqrJxy"] + } + } +} +``` + +### Failure States + +The response MUST NOT be a JSON-RPC success result in any of the following failure states. + +#### Generic Failure Code + +Unless the dapp is known to the wallet and trusted, the generic/undefined error response: + +```jsonc +{ + "id": 1, + "jsonrpc": "2.0", + "error": { + "code": 0, + "message": "Unknown error" + } +} +``` + +is RECOMMENDED for any of the following cases: + +- a `sessionId` is passed but not recognized, +- no `sessionId` is passed and only active session(s) have `sessionId`s, or +- there are no active sessions + +## Security Considerations + +The introduction of this lifecycle method must ensure that only authorized parties can retrieve the authorizations of a session. Proper authentication and authorization mechanisms must be in place to prevent unauthorized access or modifications. + +To achieve this, it is recommended to establish a connection over domain-bound or other 1:1 transports. Where applicable, additional binding to a `sessionId` is recommended to ensure secure session management. This approach helps to create a secure communication channel that can effectively authenticate and authorize session-related requests, minimizing the risk of unauthorized access or session hijacking. + +## Links + +- [CAIP-25] - JSON-RPC Handshake Protocol Specification. i.e `wallet_createSession` +- [CAIP-217]- Authorization Scopes, i.e. syntax for `scopeObject`s + +[CAIP-25]: https://chainagnostic.org/CAIPs/caip-25 +[CAIP-217]: https://chainagnostic.org/CAIPs/caip-217 + +## Copyright + +Copyright and related rights waived via +[CC0](https://creativecommons.org/publicdomain/zero/1.0/). diff --git a/CAIPs/caip-316.md b/CAIPs/caip-316.md new file mode 100644 index 00000000..cce5617e --- /dev/null +++ b/CAIPs/caip-316.md @@ -0,0 +1,156 @@ +--- +caip: 316 +title: JSON-RPC Provider Session Lifecycle Management with CAIP-25 Sessions BCP +author: [Alex Donesky] (@adonesky1) +discussions-to: https://github.com/ChainAgnostic/CAIPs/pull/285/files +status: Draft +type: Informational +created: 2024-06-07 +requires: 25, 217, 285, 311, 312 +--- + +## Simple Summary + +This overview compares new and old forms of [CAIP-25][] connection flow to ensure safe and well-informed implementation of either or both. +[CAIP-311][] and [CAIP-312][] extended [CAIP-25][] by defining new JSON-RPC methods for managing the lifecycle of authorizations within a session. +These methods allow dapps and wallets to dynamically adjust authorizations, providing more granular control and better user experience. +Additionally, it allows for session management without mandatory [sessionIds][CAIP-171], offering more flexibility in handling sessions in single-session contexts. + +## Abstract + +By loosening the earlier requirement that both caller and wallet maintain a session identifier to track the session across potentially shared or insecure transports, single-session transport options can take advantage of direct RPC calls to do more explicit session-management. + +## Motivation + +The equivalence across different transports can be counter-intuitive, so the following diagrams and examples are provided for apples-to-apples comparisons. + +## Lifecycle Equivalence Chart + +||feature|CAIP-25 now w/ sessionId|CAIP-285 w/o sessionId| +|---|---|---|---| +|1|dapp initialize (replaces session if already exist)|call [`wallet_createSession`][CAIP-25] w/o sessionId |call `wallet_createSession` w/o sessionId| +|2|wallet re-initialize|return `wallet_createSession` w/ new sessionId **next time called**|n/a (not needed because [`wallet_sessionChanged`][CAIP-311] notification can be sent, and [`wallet_getSession`][CAIP-312] can be used to confirm everything is good)| +|3|dapp get current session|n/a (should persist)|`wallet_getSession` w/o sessionId| +|4|dapp confirm current session|call `wallet_createSession` w/ sessionId and same properties OR `wallet_getSession` w/ sessionId|`wallet_getSession` w/o sessionId| +|5|dapp revoke|call `wallet_createSession` w/o sessionId and no scopes OR [`wallet_revokeSession`][CAIP-285] w/ sessionId |`wallet_revokeSession` w/o sessionId| +|6|wallet revoke|return `wallet_createSession` w/ new sessionId and no scopes **next time called** or `wallet_sessionChanged` w/ sessionId |`wallet_sessionChanged` w/o scopes| +|7|dapp update session|call `wallet_createSession` w/existing sessionId and new scopes|call `wallet_createSession` w/o sessionId| +|8|wallet update session|return `wallet_createSession` w/ new sessionId and no scopes **next time called** OR `wallet_sessionChanged` w/existing sessionId|`wallet_sessionChanged` w/o sessionId| + +## Lifecycle diagrams + +### Visualizing the lifecycle of a session without a `sessionId` + +```mermaid +sequenceDiagram + rect rgb(255, 255, 255) + actor Caller + participant Wallet + participant WalletDataStore as Data Store (Wallet) + rect rgb(255, 245, 245) + note right of Caller: Session Creation + Caller->>Wallet: wallet_createSession + Wallet->>WalletDataStore: Persist session data + Wallet-->>Caller: {"sessionScopes": {...}} + end + rect rgb(245, 255, 245) + note right of Caller: Update Session + Caller->>Wallet: wallet_createSession (update auth) + Wallet->>WalletDataStore: Update session data + Wallet-->>Caller: {"sessionScopes": {updatedScopes...}} + end + rect rgb(245, 245, 255) + note right of Caller: Connection Interrupted w/ Wallet Side Session Modification + Caller-->Wallet: Connection Interrupted + Wallet->>WalletDataStore: User initiated session change + Wallet-->Caller: wallet_sessionChanged (attempt fails) + Caller-->Wallet: Connection Re-established + end + rect rgb(255, 245, 255) + note right of Caller: Get Session + Caller->>Wallet: wallet_getSession + Wallet-->>Caller: {"sessionScopes": {...}} + end + rect rgb(255, 245, 215) + note right of Caller: Revoke Session + Caller->>Wallet: wallet_revokeSession + Wallet->>WalletDataStore: Update session data + Wallet-->>Caller: {"result": "true"} + end + end +``` + +### Visualizing the lifecycle of a session **with** a `sessionId` + +```mermaid +sequenceDiagram + rect rgb(255, 255, 255) + participant CallerDataStore as Data Store (Caller) + actor Caller + participant Wallet + participant WalletDataStore as Data Store (Wallet) + rect rgb(255, 245, 245) + note right of Caller: Session Creation + Caller->>Wallet: wallet_createSession + Wallet->>WalletDataStore: Persist session data + Wallet-->>Caller: {"sessionId": "0xdeadbeef", "sessionScopes": {...}} + Caller->>CallerDataStore: Persist session data + end + rect rgb(245, 255, 245) + note right of Caller: Update Session + Caller->>Wallet: wallet_createSession (sessionId: 0xdeadbeef, {updatedScopes...}) + Wallet->>WalletDataStore: Update session data + Wallet-->>Caller: {"sessionId": "0xdeadbeef", "sessionScopes": {(updated)sessionScopes...}} + Caller->>CallerDataStore: Persist session data + end + rect rgb(245, 245, 255) + note right of Caller: User Initiated Session Change + Wallet->>WalletDataStore: User initiated session change + Wallet->>Caller: wallet_sessionChanged (sessionId: 0xdeadbeef) + Caller->>CallerDataStore: Update session data + end + rect rgb(255, 245, 255) + note right of Caller: Revoke Session + Caller->>Wallet: wallet_createSession (sessionId: 0xnewbeef, no scopes) + Wallet->>WalletDataStore: Create new, empty session 0xnewbeef ; clear all older sessions w/same dapp + Wallet-->>Caller: {"result": "true"} (session is revoked) + Caller->>CallerDataStore: Clear session data + end + rect rgb(255, 245, 255) + note right of Caller: Revoke Session (alternate) + Caller->>Wallet: wallet_revokeSession (sessionId: 0xdeadbeef) + Wallet->>WalletDataStore: Update session data + Wallet-->>Caller: {"result": "true"} (session is revoked) + Caller->>CallerDataStore: Update session data + end + end +``` +## Privacy Considerations + +The introduction of this lifecycle method must ensure that only authorized parties can retrieve the authorizations of a session. Proper authentication and authorization mechanisms must be in place to prevent unauthorized access or modifications. + +To achieve this, it is recommended to establish a connection over domain-bound or other 1:1 transports. Where applicable, additional binding to a `sessionId` is recommended to ensure secure session management. This approach helps to create a secure communication channel that can effectively authenticate and authorize session-related requests, minimizing the risk of unauthorized access or session hijacking. +## Changelog + +- 2024-06-07: Initial draft of CAIP-285. + +## Links + + +- [CAIP-25][] - Session handshake - `wallet_createSession` - specification +- [CAIP-171][] - Session Identifier, i.e. syntax and usage of `sessionId`s +- [CAIP-217][] - Authorization Scopes, i.e. syntax for `scopeObject`s +- [CAIP-285][] - `wallet_revokeSession` Specification +- [CAIP-312][] - `wallet_getSession` Specification +- [CAIP-311][] - `wallet_sessionChanged` Specification + +[CAIP-25]: https://chainagnostic.org/CAIPs/caip-25 +[CAIP-171]: https://chainagnostic.org/CAIPs/caip-171 +[CAIP-217]: https://chainagnostic.org/CAIPs/caip-217 +[CAIP-285]: https://chainagnostic.org/CAIPs/caip-285 +[CAIP-312]: https://chainagnostic.org/CAIPs/caip-312 +[CAIP-311]: https://chainagnostic.org/CAIPs/caip-311 + +## Copyright + +Copyright and related rights waived via [CC0](../LICENSE).