From 1a834c8230fa5e1fe56c4ba633bc1fbffebb5030 Mon Sep 17 00:00:00 2001 From: Max Kalashnikoff Date: Thu, 13 Jun 2024 12:32:56 +0200 Subject: [PATCH 1/8] feat(sessions): session permissions storage API --- .../blockchain/blockchain-permissions-api.md | 108 ++++++++++++++++++ 1 file changed, 108 insertions(+) create mode 100644 docs/specs/servers/blockchain/blockchain-permissions-api.md diff --git a/docs/specs/servers/blockchain/blockchain-permissions-api.md b/docs/specs/servers/blockchain/blockchain-permissions-api.md new file mode 100644 index 00000000..eca5da98 --- /dev/null +++ b/docs/specs/servers/blockchain/blockchain-permissions-api.md @@ -0,0 +1,108 @@ +# Blockchain API Sessions and Permissions + +## Sessions permissions storage + +### Get permissions list + +Used to get account list of active sessions + +`GET /v1/sessions/{address}?projectId={projectId}` + +* `address` - CAIP-10 address format. +* `projectId` - The project identifier. + +#### Success response body: + +```typescript +{ + sessions: [] +} +``` + +#### Response error codes: + +* `400 Bad request` - Wrong requested address format. + +## Add a new permission + +Creating a new permission session for the account + +`POST /v1/sessions/{address}?projectId={projectId}` + +* `address` - CAIP-10 address format. +* `projectId` - The project identifier. + +### Request body: + +The POST request body should be in JSON format and following schema: + +```typescript +{ + message: { + permission: {}, + timestamp: string + }, + signature: string, +} +``` + +* `message` - Message that used in signature: + * `permission` - New permission object. + * `timestamp` - Current unixtime timestamp. The signature is valid for 10 seconds. +* `signature` - Ethereum signature for the signed `message` to check the address ownership. + +#### Success response body: + +Response will contain an updated list of sessions for the address. + +```typescript +{ + sessions: [] +} +``` + +#### Response error codes: + +* `400 Bad request` - Wrong format in request. + +## Revoke permission + +Revoking a permission from account sessions. + +`POST /v1/sessions/{address}/revoke/?projectId={projectId}` + +* `address` - CAIP-10 address format. +* `projectId` - The project identifier. + +### Request body: + +The POST request body should be in JSON format and following schema: + +```typescript +{ + message: { + pci: string, + timestamp: string + }, + signature: string, +} +``` + +* `message` - Message that used in signature: + * `pci` - Unique permission context identifier. + * `timestamp` - Current unixtime timestamp. The signature is valid for 10 seconds. +* `signature` - Ethereum signature for the signed `message` to check the address ownership. + +#### Success response body: + +Response will contain an updated list of sessions for the address. + +```typescript +{ + sessions: [] +} +``` + +#### Response error codes: + +* `400 Bad request` - Wrong format in request. From af5189941f61cd67279136c825fac4ae39b0ea02 Mon Sep 17 00:00:00 2001 From: Max Kalashnikoff Date: Thu, 13 Jun 2024 14:54:29 +0200 Subject: [PATCH 2/8] feat: updating schema, keys generation added --- .../blockchain/blockchain-permissions-api.md | 73 +++++++++++-------- 1 file changed, 44 insertions(+), 29 deletions(-) diff --git a/docs/specs/servers/blockchain/blockchain-permissions-api.md b/docs/specs/servers/blockchain/blockchain-permissions-api.md index eca5da98..121b7877 100644 --- a/docs/specs/servers/blockchain/blockchain-permissions-api.md +++ b/docs/specs/servers/blockchain/blockchain-permissions-api.md @@ -2,7 +2,7 @@ ## Sessions permissions storage -### Get permissions list +### Get permissions list for account Used to get account list of active sessions @@ -15,7 +15,34 @@ Used to get account list of active sessions ```typescript { - sessions: [] + pci: [string] +} +``` + +* `pci` - List of sessions PCIs for this account. + +#### Response error codes: + +* `400 Bad request` - Wrong requested address format. + +### Get permission by PCI + +Used to get permission by PCI + +`GET /v1/sessions/{address}/{pci}?projectId={projectId}` + +* `address` - CAIP-10 address format. +* `pci` - Permission identifier. +* `projectId` - The project identifier. + +#### Success response body: + +```typescript +{ + "type": string, + "data": any, + "required": bool, + "onChainValidated": bool } ``` @@ -38,26 +65,25 @@ The POST request body should be in JSON format and following schema: ```typescript { - message: { - permission: {}, - timestamp: string - }, - signature: string, + permissions:[ + { + "type": string, + "data": any, + "required": bool, + "onChainValidated": bool + } + ] } ``` -* `message` - Message that used in signature: - * `permission` - New permission object. - * `timestamp` - Current unixtime timestamp. The signature is valid for 10 seconds. -* `signature` - Ethereum signature for the signed `message` to check the address ownership. - #### Success response body: -Response will contain an updated list of sessions for the address. +Response will contain a new generated ECDSA key and PCI of the new permission. ```typescript { - sessions: [] + key: string, + pci: string } ``` @@ -80,28 +106,17 @@ The POST request body should be in JSON format and following schema: ```typescript { - message: { pci: string, - timestamp: string - }, - signature: string, + signature: string, } ``` -* `message` - Message that used in signature: - * `pci` - Unique permission context identifier. - * `timestamp` - Current unixtime timestamp. The signature is valid for 10 seconds. -* `signature` - Ethereum signature for the signed `message` to check the address ownership. +* `pci` - PCI to revoke. +* `signature` - Signature signed by the key provided during the permission creation. #### Success response body: -Response will contain an updated list of sessions for the address. - -```typescript -{ - sessions: [] -} -``` +* `202 Accepted` - Successfully revoked. #### Response error codes: From f2ecd3124bb8fd31c46d06edadba15fad6ee4d89 Mon Sep 17 00:00:00 2001 From: Max Kalashnikoff Date: Thu, 13 Jun 2024 17:37:26 +0200 Subject: [PATCH 3/8] feat: adding permissions context updating --- .../blockchain/blockchain-permissions-api.md | 47 +++++++++++++++++++ 1 file changed, 47 insertions(+) diff --git a/docs/specs/servers/blockchain/blockchain-permissions-api.md b/docs/specs/servers/blockchain/blockchain-permissions-api.md index 121b7877..ef5bff43 100644 --- a/docs/specs/servers/blockchain/blockchain-permissions-api.md +++ b/docs/specs/servers/blockchain/blockchain-permissions-api.md @@ -91,6 +91,53 @@ Response will contain a new generated ECDSA key and PCI of the new permission. * `400 Bad request` - Wrong format in request. +## Updating permissions context + +Updating permissions context for the certain permission idenitifier. + +`POST /v1/sessions/{address}/context/?projectId={projectId}` + +* `address` - CAIP-10 address format. +* `projectId` - The project identifier. + +### Request body: + +The POST request body should be in JSON format and following schema: + +```typescript +{ + pci: string, + signature: string, + context: { + { + signer: { + type: string, + ids: [string] + }, + expiry: number, + signerData: { + userOpBuilder: string + }, + factory: string, + factoryData: string, + permissionsContext: string + } + } +} +``` + +* `pci` - PCI to revoke. +* `signature` - Signature signed by the key provided during the permission creation. +* `context` - Permissions context object to update. + +#### Success response body: + +* `202 Accepted` - Successfully updated. + +#### Response error codes: + +* `400 Bad request` - Wrong format in request. + ## Revoke permission Revoking a permission from account sessions. From c5284e49048f45a96916ab381825a9e701c21ae8 Mon Sep 17 00:00:00 2001 From: Max Kalashnikoff Date: Wed, 26 Jun 2024 11:10:42 +0200 Subject: [PATCH 4/8] fix: chores, addressing comments --- .../blockchain/blockchain-permissions-api.md | 33 +++++++++---------- 1 file changed, 16 insertions(+), 17 deletions(-) diff --git a/docs/specs/servers/blockchain/blockchain-permissions-api.md b/docs/specs/servers/blockchain/blockchain-permissions-api.md index ef5bff43..f23ad9ee 100644 --- a/docs/specs/servers/blockchain/blockchain-permissions-api.md +++ b/docs/specs/servers/blockchain/blockchain-permissions-api.md @@ -9,13 +9,13 @@ Used to get account list of active sessions `GET /v1/sessions/{address}?projectId={projectId}` * `address` - CAIP-10 address format. -* `projectId` - The project identifier. +* `projectId` - Required. The project identifier. #### Success response body: ```typescript { - pci: [string] + pci: string[] } ``` @@ -33,22 +33,22 @@ Used to get permission by PCI * `address` - CAIP-10 address format. * `pci` - Permission identifier. -* `projectId` - The project identifier. +* `projectId` - Required. The project identifier. #### Success response body: ```typescript { - "type": string, - "data": any, - "required": bool, - "onChainValidated": bool + "permissionType": string, + "data": string, + "required": boolean, + "onChainValidated": boolean } ``` #### Response error codes: -* `400 Bad request` - Wrong requested address format. +* `400 Bad request` - Wrong requested address format or PCI not found. ## Add a new permission @@ -57,7 +57,7 @@ Creating a new permission session for the account `POST /v1/sessions/{address}?projectId={projectId}` * `address` - CAIP-10 address format. -* `projectId` - The project identifier. +* `projectId` - Required. The project identifier. ### Request body: @@ -65,14 +65,13 @@ The POST request body should be in JSON format and following schema: ```typescript { - permissions:[ + permission: { - "type": string, - "data": any, - "required": bool, - "onChainValidated": bool + "permissionType": string, + "data": string, + "required": boolean, + "onChainValidated": boolean } - ] } ``` @@ -98,7 +97,7 @@ Updating permissions context for the certain permission idenitifier. `POST /v1/sessions/{address}/context/?projectId={projectId}` * `address` - CAIP-10 address format. -* `projectId` - The project identifier. +* `projectId` - Required. The project identifier. ### Request body: @@ -145,7 +144,7 @@ Revoking a permission from account sessions. `POST /v1/sessions/{address}/revoke/?projectId={projectId}` * `address` - CAIP-10 address format. -* `projectId` - The project identifier. +* `projectId` - Required. The project identifier. ### Request body: From 10733a36b163ccb641ea674e9b48aeed8cb2a7fe Mon Sep 17 00:00:00 2001 From: Max Kalashnikoff Date: Tue, 9 Jul 2024 12:10:56 +0200 Subject: [PATCH 5/8] fix: adding fields description and error codes --- .../blockchain/blockchain-permissions-api.md | 27 ++++++++++++------- 1 file changed, 17 insertions(+), 10 deletions(-) diff --git a/docs/specs/servers/blockchain/blockchain-permissions-api.md b/docs/specs/servers/blockchain/blockchain-permissions-api.md index f23ad9ee..db3f46a1 100644 --- a/docs/specs/servers/blockchain/blockchain-permissions-api.md +++ b/docs/specs/servers/blockchain/blockchain-permissions-api.md @@ -1,5 +1,7 @@ # Blockchain API Sessions and Permissions +This API is **unstable**, not yet production ready and can be changed at any time. + ## Sessions permissions storage ### Get permissions list for account @@ -77,15 +79,18 @@ The POST request body should be in JSON format and following schema: #### Success response body: -Response will contain a new generated ECDSA key and PCI of the new permission. +Response will contain a new generated key and PCI of the new permission. ```typescript { - key: string, - pci: string + pci: string, + key: string } ``` +* `pci` - New unique permission controller identifier. +* `key` - Generated signing (private) ECDSA P256 key in DER, SEC1 format encoded by Base64. + #### Response error codes: * `400 Bad request` - Wrong format in request. @@ -94,7 +99,7 @@ Response will contain a new generated ECDSA key and PCI of the new permission. Updating permissions context for the certain permission idenitifier. -`POST /v1/sessions/{address}/context/?projectId={projectId}` +`POST /v1/sessions/{address}/context?projectId={projectId}` * `address` - CAIP-10 address format. * `projectId` - Required. The project identifier. @@ -110,7 +115,7 @@ The POST request body should be in JSON format and following schema: context: { { signer: { - type: string, + permissionType: string, ids: [string] }, expiry: number, @@ -126,22 +131,23 @@ The POST request body should be in JSON format and following schema: ``` * `pci` - PCI to revoke. -* `signature` - Signature signed by the key provided during the permission creation. +* `signature` - Signature of canonicalized JSON `context` object signed by the key provided during the permission creation. The signature must be provided as DER, SEC1 and encoded in Base64 format. * `context` - Permissions context object to update. #### Success response body: -* `202 Accepted` - Successfully updated. +* `200 Ok` - Successfully updated. #### Response error codes: * `400 Bad request` - Wrong format in request. +* `401 Unauthorized` - Wrong signature. ## Revoke permission Revoking a permission from account sessions. -`POST /v1/sessions/{address}/revoke/?projectId={projectId}` +`POST /v1/sessions/{address}/revoke?projectId={projectId}` * `address` - CAIP-10 address format. * `projectId` - Required. The project identifier. @@ -158,12 +164,13 @@ The POST request body should be in JSON format and following schema: ``` * `pci` - PCI to revoke. -* `signature` - Signature signed by the key provided during the permission creation. +* `signature` - Signature of signed `pci` field by the key provided during the permission creation. The signature must be provided as DER, SEC1 and encoded in Base64 format. #### Success response body: -* `202 Accepted` - Successfully revoked. +* `200 Ok` - Successfully revoked. #### Response error codes: * `400 Bad request` - Wrong format in request. +* `401 Unauthorized` - Wrong signature. From 836180f5f34eb7f7b0f992cafb670de5968f368b Mon Sep 17 00:00:00 2001 From: Max Kalashnikoff Date: Thu, 11 Jul 2024 18:47:46 +0200 Subject: [PATCH 6/8] fix: removing unstable, fixing context to be in line with ERC7715 --- .../blockchain/blockchain-permissions-api.md | 30 +++++++++---------- 1 file changed, 14 insertions(+), 16 deletions(-) diff --git a/docs/specs/servers/blockchain/blockchain-permissions-api.md b/docs/specs/servers/blockchain/blockchain-permissions-api.md index db3f46a1..65524c35 100644 --- a/docs/specs/servers/blockchain/blockchain-permissions-api.md +++ b/docs/specs/servers/blockchain/blockchain-permissions-api.md @@ -1,7 +1,5 @@ # Blockchain API Sessions and Permissions -This API is **unstable**, not yet production ready and can be changed at any time. - ## Sessions permissions storage ### Get permissions list for account @@ -106,26 +104,26 @@ Updating permissions context for the certain permission idenitifier. ### Request body: -The POST request body should be in JSON format and following schema: +The POST request body should be in JSON format and following schema based on the [ERC-7715](https://github.com/ethereum/ERCs/blob/a75e2d80698441f5da9e0fe98d38122a862aed89/ERCS/erc-7715.md#signers): ```typescript { pci: string, signature: string, context: { - { - signer: { - permissionType: string, - ids: [string] - }, - expiry: number, - signerData: { - userOpBuilder: string - }, - factory: string, - factoryData: string, - permissionsContext: string - } + signer: { + type: string, + data:{ + ids: string[], + } + }, + expiry: number, + signerData: { + userOpBuilder: string + }, + factory: string, + factoryData: string, + permissionsContext: string } } ``` From 162a7fe030a8428736507d4c29e31261397c187f Mon Sep 17 00:00:00 2001 From: Max Kalashnikoff Date: Mon, 22 Jul 2024 17:15:13 +0200 Subject: [PATCH 7/8] fix: key format changes, chores --- .../blockchain/blockchain-permissions-api.md | 40 +++++++------------ 1 file changed, 14 insertions(+), 26 deletions(-) diff --git a/docs/specs/servers/blockchain/blockchain-permissions-api.md b/docs/specs/servers/blockchain/blockchain-permissions-api.md index 65524c35..855fdba6 100644 --- a/docs/specs/servers/blockchain/blockchain-permissions-api.md +++ b/docs/specs/servers/blockchain/blockchain-permissions-api.md @@ -15,15 +15,13 @@ Used to get account list of active sessions ```typescript { - pci: string[] + pci: string[] // List of sessions PCIs for this account } ``` -* `pci` - List of sessions PCIs for this account. - #### Response error codes: -* `400 Bad request` - Wrong requested address format. +* `400 Bad request` - Invalid requested address format. ### Get permission by PCI @@ -48,7 +46,7 @@ Used to get permission by PCI #### Response error codes: -* `400 Bad request` - Wrong requested address format or PCI not found. +* `400 Bad request` - Invalid requested address format or PCI not found. ## Add a new permission @@ -81,17 +79,14 @@ Response will contain a new generated key and PCI of the new permission. ```typescript { - pci: string, - key: string + pci: string, // New unique permission controller identifier. + key: string // Public (verifying) secp256k1 key for the generated PCI key in sec1/der format encoded by base64. } ``` -* `pci` - New unique permission controller identifier. -* `key` - Generated signing (private) ECDSA P256 key in DER, SEC1 format encoded by Base64. - #### Response error codes: -* `400 Bad request` - Wrong format in request. +* `400 Bad request` - Invalid parameter format in request. ## Updating permissions context @@ -108,8 +103,8 @@ The POST request body should be in JSON format and following schema based on the ```typescript { - pci: string, - signature: string, + pci: string, // PCI to update + signature: string, // Signature of canonicalized JSON `context` object signed by the key provided during the permission creation. The signature must be provided as DER, SEC1 and encoded in Base64 format. context: { signer: { type: string, @@ -128,18 +123,14 @@ The POST request body should be in JSON format and following schema based on the } ``` -* `pci` - PCI to revoke. -* `signature` - Signature of canonicalized JSON `context` object signed by the key provided during the permission creation. The signature must be provided as DER, SEC1 and encoded in Base64 format. -* `context` - Permissions context object to update. - #### Success response body: * `200 Ok` - Successfully updated. #### Response error codes: -* `400 Bad request` - Wrong format in request. -* `401 Unauthorized` - Wrong signature. +* `400 Bad request` - Invalid parameter format in request. +* `401 Unauthorized` - Invalid signature. ## Revoke permission @@ -156,19 +147,16 @@ The POST request body should be in JSON format and following schema: ```typescript { - pci: string, - signature: string, + pci: string, // PCI to revoke. + signature: string, // Signature of signed `pci` field by the key provided during the permission creation. The signature must be provided as DER, SEC1 and encoded in Base64 format. } ``` -* `pci` - PCI to revoke. -* `signature` - Signature of signed `pci` field by the key provided during the permission creation. The signature must be provided as DER, SEC1 and encoded in Base64 format. - #### Success response body: * `200 Ok` - Successfully revoked. #### Response error codes: -* `400 Bad request` - Wrong format in request. -* `401 Unauthorized` - Wrong signature. +* `400 Bad request` - Invalid parameter format in request. +* `401 Unauthorized` - Invalid signature. From e471921e3fd2aed2a39c19b2b08f4bc685e19884 Mon Sep 17 00:00:00 2001 From: Max Kalashnikoff Date: Thu, 3 Oct 2024 20:09:01 +0200 Subject: [PATCH 8/8] fix: return all permissions by address --- .../blockchain/blockchain-permissions-api.md | 34 ++++++++++++++----- 1 file changed, 26 insertions(+), 8 deletions(-) diff --git a/docs/specs/servers/blockchain/blockchain-permissions-api.md b/docs/specs/servers/blockchain/blockchain-permissions-api.md index 855fdba6..1f2894c2 100644 --- a/docs/specs/servers/blockchain/blockchain-permissions-api.md +++ b/docs/specs/servers/blockchain/blockchain-permissions-api.md @@ -23,24 +23,42 @@ Used to get account list of active sessions * `400 Bad request` - Invalid requested address format. -### Get permission by PCI +### Get permissions by address -Used to get permission by PCI +Used to get permissions by address -`GET /v1/sessions/{address}/{pci}?projectId={projectId}` +`GET /v1/sessions/{address}?projectId={projectId}` * `address` - CAIP-10 address format. -* `pci` - Permission identifier. * `projectId` - Required. The project identifier. #### Success response body: +The response is a list of PCIs with permissions and policy: + ```typescript { - "permissionType": string, - "data": string, - "required": boolean, - "onChainValidated": boolean + "pcis": [pci] +} +``` + +The `pci` object: + +```typescript +{ + "project": + { + "id": string, + "name": string, + "url": ?string, + "iconUrl": ?string, + } + "pci": string, + "expiration": number, + "createdAt": number, + "permissions": [permission] + "policies": [policy], + "context": string } ```