org.bdinetwork.ishare.client — org.bdinetwork/clj-ishare-client 1.0.0

Provides an iSHARE-compatible HTTP client.

The iSHARE client allows for automatic authentication of requests and adherence checks of contacted services.

The client namespace provides *-request functions to build HTTP requests, and an exec function with iSHARE specific middleware to execute the created requests.

Configuring

The client is configured by passing namespaced keys to the request builders:

(require '[org.bdinetwork.ishare.client :as client])
(require '[org.bdinetwork.ishare.client.request :as request])

(def config {:ishare/satellite-base-url "http://example.com"
             :ishare/private-key ....
             :ishare/x5c ...
             ...}

(-> config ;; start from base config
    ;; add specific config for this request
    (assoc :ishare/server-id "some-server"
           :ishare/base-url "https://some.other.example.com")
    ;; request for standardized "/capabilities" endpoint
    (request/capabilities-request)
    ;; execute request
    (client/exec))

Request builders

Request builder functions are available in the org.bdinetwork.ishare.client.request namespace.

Configuration keys

The following keywords can be provided in requests.

:ishare/satellite-base-url - The URL of the iSHARE Satellite to use when obtaining party information.

:ishare/satellite-id - The ID of the iSHARE Satellite to use when obtaining party information.

:ishare/x5c - The full certificate chain to use for authentication, as a vector of X509 certificates, can be created by the x5c function.

:ishare/private-key - The private key to use for authentication, can be created by the private-key function.

:ishare/client-id - The client ID to use for authentication. The client ID, certificate chain and private key must match the client's registration in the iSHARE Satellite.

:ishare/bearer-token - The access token to use for the current request, used by bearer-token-interceptor. If not provided, the fetch-bearer-token-interceptor will attempt to authenticate and fetch an access token`.

:ishare/base-url - used by build-uri-interceptor to create a full :uri for the given request, if :path is also present. If :uri is already present, :ishare/base-url and :path can be omitted.

:ishare/dataspace-id - the Dataspace ID to be used for the request. This is relevant for fetch-issuer-ar-interceptor but may be used in other contexts in the future.

:ishare/check-server-adherence? - defaults to true, meaning that before contacting a server, the server's party info will be requested from the Satellite. If the server is not currently adherent and active, an exception is raised. If :ishare/check-server-adherence? is provided and false, this check is disabled.

:ishare/unsign-token - if provided, specifies a attribute which, if present in the response body, has an iSHARE JWT value that should be validated and decoded using org.bdinetwork.ishare.jwt/unsign-token.

:ishare/lens - path to the "result" in the response map; the object at the path will be placed in the resonse under :ishare/result

Informational keys

The following keywords may be added by middleware or request builders. If the

:ishare/server-name - added to request by fetching the server info from the iSHARE Satellite. Will not be added if :ishare/check-server-adherence? is false.

:ishare/server-adherent? - added to request by fetching the server info from the iSHARE Satellite. Will not be added if :ishare/check-server-adherence? is false.

:ishare/policy-issuer - the policy issuer to be used for a delegation-evidence-request. This is relevant for fetch-issuer-ar-interceptor

:ishare/operation - marks the request type as generated by the *-request builders.

:ishare/result - if present in the response, represents "the result" of executing the request. For standard iSHARE requests, this is generally the (decoded) result token.

Interceptors / middleware

The org.bdinetwork.ishare.client.interceptors namespace contains the client middleware for processing requests and responses during execution.

default-http-client clj

exec clj

(exec request)

Execute an iSHARE request.

See org.bdinetwork.ishare.client namespace documentation.

See org.bdinetwork.ishare.client.request for request builders.

http-client clj

private-key clj

(private-key key-file)

Read private key from file.

x5c clj

(x5c x5c-file)

Read x5c-file into vector of certificates.

The x5c-file must be the path to a PEM file containing multiple X509 certificates.