Using Server Proxy

Introduction

The Minka Server Proxy is a local proxy server that automatically handles request signing when interacting with the Minka Ledger API. This tool simplifies the process of making authenticated requests by managing signatures and JWT tokens automatically, making it particularly useful when testing with tools like Postman or developing applications.

Getting started

In order to follow this tutorial you have to have nodeJS v20 or newer installed on your machine. This tutorial uses a Minka Ledger and our first task is to connect to it.

Install the Minka CLI through your terminal:

npm install -g @minka/cli

You will need a signer that will be used for request signing. Create one, if you don't have it:

minka signer create

Also, Minka CLI has to be connected to a ledger server. Proxy instance will pass your requests to this ledger server. You can connect using the following command:

minka server connect

Starting the Proxy Server

Now that we have a server connection and a signer, we can start the proxy server:

$ minka server proxy
? Select signer: proxy-signer
? Signer password for proxy-signer: [hidden]

✅ Proxy server is running on port 4050.
Press ctrl + c to exit.

Waiting for requests...

Remember to stop the proxy server when you're done by pressing Ctrl + C in the terminal where it's running.

Making Requests

Once the proxy server is running, you can send requests through it instead of directly to the Ledger API. The proxy will automatically handle:

• Adding signatures to request bodies
• Including JWT tokens in headers
• Forwarding requests to the Ledger API

Example: Reading Wallets

Here's how to fetch a list of wallets through the proxy:

curl http://localhost:4050/wallets \
  -H "x-ledger: your-ledger-handle"

Example: Creating a Wallet

Creating a new wallet through the proxy:

curl http://localhost:4050/wallets \
  -H "Content-Type: application/json" \
  -H "x-ledger: your-ledger-handle" \
  -d '{
    "data": {
      "handle": "test_wallet",
      "access": [
        {
          "action": "any"
        }
      ]
    }
  }'

Understanding Proxy Behavior

In Minka Ledger API, there are many kinds of objects (or records) - anchor, effect, intent, wallet, symbol, etc. Most important thing to note is that they share very similar or even identical pattern of how they are handled. This will be explained in the following sections.

Authorization header

Proxy automatically adds a JWT token in the Authorization header for all types of requests.

GET requests for listing records, reading individual records, etc.

Proxy passes these requests without modifying them, except for adding the authorization header.

POST requests for creating a record, checking access rights, etc.

When using POST requests for creating a record or checking access rights, you need to send data in the request body. Proxy will automatically:

1. Take data component of the request body, calculate its hash value and include it in the request body under hash key.
2. Sign the calculated hash using your selected signer and include the signature in meta/proofs list.

POST requests for adding proofs to existing records

For endpoints that end in /proofs, the proxy will:

1. Fetch the latest record data.
2. Fetch ledger record's hash.
3. Create the proof using selected signer.
4. Include any custom data you provided.

PUT requests for updating existing records

When using PUT requests for updating an existing record, you need to send data (with parent value included) and luid in the request body. Proxy will automatically:

1. Take data component of the request body, calculate its hash value and include it in the request body under hash key.
2. Sign the calculated hash using your selected signer and include the signature in meta/proofs list.

Deleting a record using POST or DELETE request

When using POST or DELETE endpoints for deleting a record, you need to send data (with parent value included) and luid in the request body. Proxy will automatically:

1. Take data component of the request body, calculate its hash value and include it in the request body under hash key.
2. Sign the calculated hash using your selected signer and include the signature in meta/proofs list.

Security Considerations

• The proxy server is intended for development and testing
• For production environments, implement proper request signing in your application