interface.rst

Interface

Client

When enabled in a Tahoe-LAFS client node, ZKAPAuthorizer publishes an HTTP-based interface inside the main Tahoe-LAFS web interface.

All endpoints in the interface require an authorization token. Without the token, requests will receive an HTTP UNAUTHORIZED (401) response.

To be authorized to access the resources at the endpoints, requests must include the correct secret token in the value for Authorization in the request header. For example, if the secret token is ABCDEF:

Authorization: tahoe-lafs ABCDEF

The correct value for the token can be read from the Tahoe-LAFS node's private/api_auth_token file.

GET /storage-plugins/privatestorageio-zkapauthz-v2/version

This endpoint returns the version of the ZKAPAuthorizer Python package in use by the Tahoe-LAFS client node.

The response is OK with an application/json Content-Type:

{ "version": <string>
}

PUT /storage-plugins/privatestorageio-zkapauthz-v2/voucher

This endpoint allows an external agent which has submitted a payment to cause the plugin to redeem the voucher for tokens. The request body for this endpoint must have the application/json content-type. The request body contains a simple json object containing the voucher:

{"voucher": "<voucher>"}

The endpoint responds to such a request with an OK HTTP response code if the voucher is accepted for processing. If the voucher cannot be accepted at the time of the request then the response code will be anything other than OK.

If the response is OK then a repeated request with the same body will have no effect. If the response is not OK then a repeated request with the same body will try to accept the number again.

GET /storage-plugins/privatestorageio-zkapauthz-v2/voucher/<voucher>

This endpoint allows an external agent to monitor the status of the redemption of a voucher. This endpoint accepts no request body.

If the voucher is not known then the response is NOT FOUND. For any voucher which has previously been submitted, the response is OK with an application/json content-type response body like:

{ "version": 1
, "number": <string>
, "expected-tokens": <integer>
, "created": <iso8601 timestamp>
, "state": <state object>
}

The version property indicates the semantic version of the data being returned. When properties are removed or the meaning of a property is changed, the value of the version property will be incremented. The addition of new properties is not accompanied by a bumped version number.

The number property merely indicates the voucher which was requested. The expected-tokens property indicates the total number of ZKAPs for which the client intends to redeem the voucher. Vouchers created using old versions of ZKAPAuthorizer will have a best-guess value here because the real value was not recorded. The created property indicates when the voucher was first added to the node. The state property is an object that gives more details about the current state of the voucher. The following values are possible:

{ "name": "pending"
, "counter": <integer>
}

The integer counter value indicates how many successful sub-redemptions have completed for this voucher.

{ "name": "redeeming"
, "started": <iso8601 timestamp>
, "counter": <integer>
}

The started timestamp gives the time when the most recent redemption attempt began. The integer counter value has the same meaning as it does for the pending state.

{ "name": "redeemed"
, "finished": <iso8601 timestamp>
, "token-count": <number>
}

The finished timestamp gives the time when redemption completed successfully. The integer token-count gives the number tokens for which the voucher was redeemed.

{ "name": "double-spend"
, "finished": <iso8601 timestamp>
}

The finished timestamp gives the time when the double-spend error was encountered.

{ "name": "unpaid"
, "finished": <iso8601 timestamp>
}

The finished timestamp gives the time when the unpaid error was encountered.

{ "name": "error"
  "finished": <iso8601 timestamp>
, "details": <text>
}

The finished timestamp gives the time when this other error condition was encountered. The details string may give additional details about what the error was.

GET /storage-plugins/privatestorageio-zkapauthz-v2/voucher

This endpoint allows an external agent to retrieve the status of all vouchers. This endpoint accepts no request body.

The response is OK with application/json content-type response body like:

{"vouchers": [<voucher status object>, ...]}

The elements of the list are objects like the one returned by issuing a GET to a child of this collection resource.

GET /storage-plugins/privatestorageio-zkapauthz-v2/lease-maintenance

This endpoint allows an external agent to retrieve information about automatic spending for lease maintenance.

This endpoint accepts no request body.

The response is OK with application/json content-type response body like:

{ "spendable": <integer>
, "lease-maintenance-spending": <spending object>
}

The value associated with spendable gives the number of unblinded tokens in the node's database which can actually be spent.

The <spending object> may be null if the lease maintenance process has never run. If it has run, <spending object> has two properties:

• when: associated with an ISO8601 datetime string giving the approximate time the process ran
• count: associated with a number giving the number of passes which would need to be spent to renew leases on all stored objects seen during the lease maintenance activity

POST /storage-plugins/privatestorageio-zkapauthz-v2/calculate-price

This endpoint allows an agent to calculate the number of ZKAPs it will cost to store a collection of files of specified sizes. This is intended as the basis for tools which aid in user understanding of the cost of their actions.

The request body must be application/json encoded and contain an object like:

{ "version": 1
, "sizes: [ <integer>, ... ]
}

The version property must currently be 1. The sizes property is a list of integers giving file sizes in bytes.

The response is OK with application/json content-type response body like:

{ "price": <integer>, "period": <integer> }

The price property gives the number of ZKAPs which would have to be spent to store files of the given sizes. The period property gives the number of seconds those files would be stored by spending that number of ZKAPs.

The price obtained this way is valid in two scenarios. First, the case where none of the files have been uploaded yet. In this case uploading the files and storing them for period seconds will cost price ZKAPs. Second, the case where the files have already been uploaded but their leases need to be renewed. In this case, renewing the leases so they last until period seconds after the current time will cost price ZKAPs. Note that in this case any lease time currently remaining on any files has no bearing on the calculated price.