SolarNetwork Core

Class: AuthorizationV2Builder

net~ AuthorizationV2Builder

A builder object for the SNWS2 HTTP authorization scheme.

This builder can be used to calculate a one-off header value, for example:

let authHeader = new AuthorizationV2Builder("my-token")
    .path("/solarquery/api/v1/pub/...")
    .build("my-token-secret");

Or the builder can be re-used for a given token:

// create a builder for a token
let builder = new AuthorizationV2Builder("my-token");

// elsewhere, re-use the builder for repeated requests
builder.reset()
    .path("/solarquery/api/v1/pub/...")
    .build("my-token-secret");

Additionally, a signing key can be generated and re-used for up to 7 days:

// create a builder for a token
let builder = new AuthorizationV2Builder("my-token")
  .saveSigningKey("my-token-secret");

// elsewhere, re-use the builder for repeated requests
builder.reset()
    .path("/solarquery/api/v1/pub/...")
    .buildWithSavedKey(); // note previously generated key used

new AuthorizationV2Builder(token [, environment])

Constructor.

Parameters:
Name Type Argument Description
token string

the auth token to use
environment module:net~Environment <optional>

the environment to use; if not provided a default environment will be created

Members

environment :module:net~Environment

The SolarNet environment.

Type:

<readonly> requestDateHeaderValue :string

The authorization request date as a HTTP header string value.

Type:
  • string

<readonly> signingKeyValid :boolean

Test if a signing key is present and not expired.

Type:
  • boolean

tokenId :string

The SolarNet auth token value.

Type:
  • string

useSnDate :boolean

Control using the X-SN-Date HTTP header versus the Date header.

Set to true to use the X-SN-Date header, false to use the Date header. This will return true if X-SN-Date has been added to the signedHeaderNames property or has been added to the httpHeaders property.

Type:
  • boolean

Methods

build(tokenSecret)

Compute a HTTP Authorization header value from the configured properties on the builder, computing a new signing key based on the configured module:net~AuthorizationV2Builder#date.

Parameters:
Name Type Description
tokenSecret string

the secret to sign the authorization with
Returns:

the SNWS2 HTTP Authorization header value

Type
string

buildCanonicalRequestData()

Compute the canonical request data that will be included in the data to sign with the request.

Returns:

the canonical request data

Type
string

buildWithSavedKey()

Compute a HTTP Authorization header value from the configured properties on the builder, using a signing key configured from a previous call to module:net~AuthorizationV2Builder#saveSigningKey.

Returns:

the SNWS2 HTTP Authorization header value.

Type
string

canonicalContentSHA256()

Get the canonical request content SHA256 digest, hex encoded.

Returns:

the hex-encoded SHA256 digest of the request content

Type
string

canonicalHeaderNames()

Compute the canonical HTTP header names to include in the signature.

Returns:

the sorted, lower-cased HTTP header names to include

Type
Array.<string>

canonicalHeaders(sortedLowercaseHeaderNames)

Compute the canonical HTTP headers string value.

Parameters:
Name Type Description
sortedLowercaseHeaderNames Array.<string>

the sorted, lower-cased HTTP header names to include
Returns:

the canonical headers string value

Type
string

canonicalQueryParameters()

Compute the canonical query parameters.

Returns:

the canonical query parameters string value

Type
string

contentSHA256(digest)

Set the HTTP request body content SHA-256 digest value.

Parameters:
Name Type Description
digest string | module:crypto-js/enc-hex~WordArray

the digest value to use; if a string it is assumed to be Hex encoded
Returns:

this object

Type
module:net~AuthorizationV2Builder

contentType(val)

Set the HTTP content type.

This is a shortcut for calling HttpHeaders#put with the key HttpHeaders#CONTENT_TYPE.

Parameters:
Name Type Description
val string

the HTTP content type value to use
Returns:

this object

Type
module:net~AuthorizationV2Builder

date(val)

Set the authorization request date.

Parameters:
Name Type Description
val Date

the date to use; typically the current time, e.g. new Date()
Returns:

this object

Type
module:net~AuthorizationV2Builder

Set a HTTP header value.

This is a shortcut for calling HttpHeaders#put(headerName, val).

Parameters:
Name Type Description
headerName string

the header name to set
headerValue string

the header value to set
Returns:

this object

Type
module:net~AuthorizationV2Builder

headers(headers)

Set the HTTP headers to use with the request.

The headers object must include all headers necessary by the authentication scheme, and any additional headers also configured via module:net~AuthorizationV2Builder#signedHttpHeaders.

Parameters:
Name Type Description
headers HttpHeaders

the HTTP headers to use
Returns:

this object

Type
module:net~AuthorizationV2Builder

host(val)

Set the HTTP host.

This is a shortcut for calling HttpHeaders#put(HttpHeaders.HOST, val).

Parameters:
Name Type Description
val string

the HTTP host value to use
Returns:

this object

Type
module:net~AuthorizationV2Builder

method(val)

Set the HTTP method (verb) to use.

Parameters:
Name Type Description
val string

the method to use; see the HttpMethod enum for possible values
Returns:

this object

Type
module:net~AuthorizationV2Builder

path(val)

Set the HTTP request path to use.

Parameters:
Name Type Description
val string

the request path to use
Returns:

this object

Type
module:net~AuthorizationV2Builder

queryParams(params)

Set the HTTP GET query parameters, or POST form-encoded parameters.

Parameters:
Name Type Description
params MultiMap | Object

the parameters to use, as either a MultiMap or simple Object
Returns:

this object

Type
module:net~AuthorizationV2Builder

reset()

Reset to defalut property values.

Returns:

this object

Type
module:net~AuthorizationV2Builder

saveSigningKey(tokenSecret)

Compute and cache the signing key.

Signing keys are derived from the token secret and valid for 7 days, so this method can be used to compute a signing key so that module:net~AuthorizationV2Builder#build can be called later. The signing date will be set to whatever date is currently configured via module:net~AuthorizationV2Builder#date, which defaults to the current time for newly created builder instances.

Parameters:
Name Type Description
tokenSecret string

the secret to sign the digest with
Returns:

this object

Type
module:net~AuthorizationV2Builder

signedHttpHeaders(signedHeaderNames)

Set additional HTTP header names to sign with the authentication.

Parameters:
Name Type Description
signedHeaderNames Array.<sring>

additional HTTP header names to include in the signature
Returns:

this object

Type
module:net~AuthorizationV2Builder

snDate(enabled)

Set the useSnDate property.

Parameters:
Name Type Description
enabled boolean

true to use the X-SN-Date header, false to use Date
Returns:

this object

Type
module:net~AuthorizationV2Builder

url(url)

Set the host, path, and query parameters via a URL string.

Parameters:
Name Type Description
url string

the URL value to use
Returns:

this object

Type
module:net~AuthorizationV2Builder