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.
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:
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.
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.
The permissions are implemented as an allow list, linked to the token. The database holds the token with the associated actions which are allowed:
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:
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 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.
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.
