Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat(sessions): session permissions storage API #242

Open
wants to merge 8 commits into
base: main
Choose a base branch
from
180 changes: 180 additions & 0 deletions docs/specs/servers/blockchain/blockchain-permissions-api.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,180 @@
# Blockchain API Sessions and Permissions

## Sessions permissions storage

### Get permissions list for account

Used to get account list of active sessions
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We need either a new endpoint for revoked sessions, or including a field in the pci that includes the "status" ; else we cannot displayed previously revoked sessions on the ui


`GET /v1/sessions/{address}?projectId={projectId}`

* `address` - CAIP-10 address format.
* `projectId` - Required. The project identifier.

#### Success response body:

```typescript
{
pci: string[] // List of sessions PCIs for this account
}
```

#### Response error codes:

* `400 Bad request` - Invalid requested address format.

### Get permissions by address

Used to get permissions by address

`GET /v1/sessions/{address}?projectId={projectId}`

* `address` - CAIP-10 address format.
* `projectId` - Required. The project identifier.

#### Success response body:

The response is a list of PCIs with permissions and policy:

```typescript
{
"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
}
```

#### Response error codes:

* `400 Bad request` - Invalid requested address format or PCI not found.

## Add a new permission

Creating a new permission session for the account

`POST /v1/sessions/{address}?projectId={projectId}`

* `address` - CAIP-10 address format.
* `projectId` - Required. The project identifier.

### Request body:

The POST request body should be in JSON format and following schema:

```typescript
{
permission:
{
"permissionType": string,
"data": string,
"required": boolean,
"onChainValidated": boolean
}
}
```

Comment on lines +80 to +93

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Request body should have permission struct defined in ERC7715 + extra field onChainValidated if needed but not sure how will Dapp/Client know this( onChainValidated ) information.

#### Success response body:

Response will contain a new generated key and PCI of the new permission.

```typescript
{
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.
}
```

#### Response error codes:

* `400 Bad request` - Invalid parameter 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` - Required. The project identifier.

### Request body:

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, // 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,
data:{
ids: string[],
}
},
expiry: number,
signerData: {
userOpBuilder: string
},
factory: string,
factoryData: string,
permissionsContext: string
}
}
```

#### Success response body:

* `200 Ok` - Successfully updated.

#### Response error codes:

* `400 Bad request` - Invalid parameter format in request.
* `401 Unauthorized` - Invalid signature.

## Revoke permission

Revoking a permission from account sessions.

`POST /v1/sessions/{address}/revoke?projectId={projectId}`

* `address` - CAIP-10 address format.
* `projectId` - Required. The project identifier.

### Request body:

The POST request body should be in JSON format and following schema:

```typescript
{
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.
}
```

#### Success response body:

* `200 Ok` - Successfully revoked.

#### Response error codes:

* `400 Bad request` - Invalid parameter format in request.
* `401 Unauthorized` - Invalid signature.