Calimero Gateway is the service responsible for allowing or rejecting requests towards private shard components. Calimero is private by nature, and the gateway is the component which allows authorized users and applications to interact with the private shard. To allow an access control more detailed than just allow/deny, permissions are implemented on the gateway level. They allow a private shard administrator to grant users permissions to do only certain actions.

Incoming requests

All requests towards the private shard are routed through the gateway. Accessing the blockchain means sending requests to the RPC nodes or querying the indexer nodes. Today, we will focus on the RPC node permissions.

The structure of a request towards the RPC node can be studied at NEAR docs, but the essentials are:

• each request contains a request object
• the request object contains the method field and the params object
• the params object contains the request_type field

Additionally, to keep the private shard private, the requests must have an authorization token in the request header. Requests without the token in an authorization header are immediately rejected.

Authorization

The requests are authorized by using an authorization token. Calimero Console uses a custom authorization header, the near-cli uses the x-api-key header, while applications can use either the standard authorization or the x-api-key header, along with the authorization token issued from the Calimero Console.

Permissions

The permissions are implemented as an allow list, linked to the token. The database holds the token with the associated actions which are allowed:

• write (execute transactions on the blockchain)
• view transaction status
• view account keys
• view the state of accounts
• view the contract state
• view block details
• view chunk details

Alongside the actions, the database holds the ID of the shard where these actions can be performed.

Let's take a look at this example

A request comes to the gateway to access the RPC node of a shard called myshard with the following fields:

• headers: authorization is 0123456789abcdef
• method: query
• params: request type view_account

The supplied token (0123456789abcdef) is looked up in the database, and the assigned permissions are loaded. If the loaded permissions explicitly or implicitly allow the token to call the view_account functionality on myshard private shard, the request is proxied to the RPC node.

There are two cases where the request would be rejected:

• the token 0123456789abcdef doesn’t exist in the database: the request is rejected with the 401 status code
• the token 0123456789abcdef exists in the database, but it doesn’t have permission for the view_account request: the request is rejected with the 403 status code

The request can come from the Calimero Console, from a CLI or from a dApp for which an authorization token was issued. The process of accepting or rejecting the request is source-agnostic.

A fine grained future

The current permissions implementation can be further improved by allowing to filter by more than just the request type, most notably the sender/receiver account ID, paving the path to a fully featured permissioned explorer. This feature is in the Calimero roadmap, planned for Q2 2023.

‍