Protocol Specification
This page specifies how clients (that request a resource) and servers (that provide a resource) interact with each other.
Last updated
This page specifies how clients (that request a resource) and servers (that provide a resource) interact with each other.
Last updated
This page was copied from https://github.com/Conshax/OCPS/blob/main/example-implementation.md with the permission of Conshax.
The following sections provide a fine-grained explanation of the protocol that can be used as a template for clients and hosts that want to support the OCPS.
If you are just looking for a quick way to get started, refer to the Example Implementation page instead.
When a client that does not support LSAT request a protected resource, the server simply responds with the free part of the protected audio file. This is the case for both download and streaming requests.
1. Client requests a protected resource
A client tells the server that it supports LSAT by setting the X-Accept-Authenticate header.
{% tabs %} {% tab title="Recommended: Header" %}
{% endtab %}
{% tab title="Alternative: Query parameter" %} If the client is unable to set custom headers, it can set the information as a query parameter.
{% endtab %} {% endtabs %}
The server responds with status code 402 and communicates the payment information in the WWW-Authenticate header. This information identifies a unique recipient, the payment verifier, and a minimum amount that must be sent to that recipient to access the resource.
{% tabs %} {% tab title="Recommended: Header" %}
See streams vs download for more information on Lsat-Free-Content-Length. {% endtab %}
{% tab title="Alternative: Response body" %} To support clients that cannot read this header, the server also returns this information in the response body.
{% endtab %} {% endtabs %}
2. Client identifies additional payment recipients and conducts payments
A podcast episode can have multiple recipients that are defined in the episode's podcast:value tag. The payment verifier (from step 1) is always listed as a value recipient in the RSS feed:
The client uses the suggested attribute as the (minimum) total amount, calculates the individual amounts and makes one keysend payment per valueRecipient. The payments must at least include the episode_guid property to make the payment relatable to the episode (blip-10). We recommend to provide all known blip-10 properties, to set the action to “lsat", and to set a token property to the value of the token provided by the server (see step 1).
The client stores the preimage of the keysend payment to the payment verifier (from step 1) in a local variable.\
3. Client requests full resource using payment preimage
The client requests the full resource by setting the hex representation of the keysend payment preimage to the payment verifier** ** (see step 1) and the token (also received in step 1) in the Authorization header.
If the client is unable to set custom headers, it can set the information as a URL encoded query parameter.
{% tabs %} {% tab title="Recommended: Header" %}
{% endtab %}
{% tab title="Alternative: Query parameter" %}
{% endtab %} {% endtabs %}
The server uses the preimage to verify that the authenticating payment was made and is related to the requested resource. If that is the case, the server returns the full resource:
When a client wants to stream an audio file, it doesn't want to download the whole file before it can start playing. Instead, the client repeatedly queries a specific part of the audio file using the Range header.
The Range must be set via header. OCPS specific parameters can still be set via header or query parameter in range requests.
Stream request spec:
{% tabs %} {% tab title="Free range" %} Client request:
Server response:
{% endtab %}
{% tab title="Protected range (before payment)" %} Client request:
Server response:
{% endtab %}
{% tab title="Protected range (after payment)" %} Client request:
Server response:
{% endtab %} {% endtabs %}