Class 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

Post requests

For handling POST or PUT requests, you must make sure to configure the properties of this class to match your actual HTTP request:

  1. Use the method() method to configure the HTTP verb (you can use the HttpMethod constants).
  2. Use the contentType() method to configure the same value that will be used for the HTTP Content-Type header (you can use the HttpContentType constants).
  3. If the content type is application/x-www-form-urlencoded then you should use the queryParams() method to configure the request parameters.
  4. If the content type is not application/x-www-form-urlencoded then you should use the computeContentDigest() method to configure a HTTP Digest header.
// create a builder for a token
let builder = new AuthorizationV2Builder("my-token")
  .saveSigningKey("my-token-secret");

// POST request with form data
builder.reset()
    .method(HttpHeaders.POST)
    .path("/solarquery/api/v1/pub/...")
    .contentType(HttpContentType.FORM_URLENCODED_UTF8)
    .queryParams({foo:"bar"})
    .buildWithSavedKey();

// PUT request with JSON data, with XHR style request
let reqJson = JSON.stringify({foo:"bar"});
builder.reset()
    .method(HttpHeaders.PUT)
    .path("/solarquery/api/v1/pub/...")
    .contentType(HttpContentType.APPLICATION_JSON_UTF8)
    .computeContentDigest(reqJson);

// when making actual HTTP request, re-use the computed HTTP Digest header:
xhr.setRequestHeader(
    HttpHeaders.DIGEST,
    builder.httpHeaders.firstValue(HttpHeaders.DIGEST)
);
xhr.setRequestHeader(HttpHeaders.X_SN_DATE, builder.requestDateHeaderValue);
xhr.setRequestHeader(HttpHeaders.AUTHORIZATION, builder.buildWithSavedKey());

Hierarchy

  • AuthorizationV2Builder

Constructors

constructor

Properties

#contentDigest? #httpMethod #requestDate #requestPath #signedHeaderNames? #signingKey? #signingKeyExpiration? environment forceHostPort httpHeaders parameters tokenId? EMPTY_STRING_SHA256_HEX SNWS2_AUTH_SCHEME

Accessors

requestDateHeaderValue signingKeyExpirationDate signingKeyValid useSnDate

Methods

#canonicalSignedHeaderNames #computeCanonicalRequestData build buildCanonicalRequestData buildWithKey buildWithSavedKey canonicalContentSHA256 canonicalHeaderNames canonicalHeaders canonicalQueryParameters computeContentDigest computeSignatureData computeSigningKey contentSHA256 contentType date header headers host key method path queryParams reset saveSigningKey signedHttpHeaders snDate url

Constructors

constructor

Properties

Private Optional #contentDigest

#contentDigest?: WordArray

Private #httpMethod

#httpMethod: string

Private #requestDate

#requestDate: Date

Private #requestPath

#requestPath: string

Private Optional #signedHeaderNames

#signedHeaderNames?: string[]

Private Optional #signingKey

#signingKey?: WordArray

Private Optional #signingKeyExpiration

#signingKeyExpiration?: Date

environment

environment: HostConfig

The SolarNet environment.

forceHostPort

forceHostPort: boolean

Force a port number to be added to host values, even if port would be implied.

This can be useful when working with a server behind a proxy, where the proxy is configured to always forward the port even if the port is implied (i.e. HTTPS is used on the standard port 443).

httpHeaders

httpHeaders: HttpHeaders

The signed HTTP headers.

parameters

parameters: MultiMap

The HTTP query parameters.

Optional tokenId

tokenId?: string

The SolarNet auth token value.

Static Readonly EMPTY_STRING_SHA256_HEX

EMPTY_STRING_SHA256_HEX: "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"

The hex-encoded value for an empty SHA256 digest value.

Static Readonly SNWS2_AUTH_SCHEME

SNWS2_AUTH_SCHEME: "SNWS2" = "SNWS2"

The SolarNetwork V2 authorization scheme.

Accessors

requestDateHeaderValue

  • get requestDateHeaderValue(): undefined | string

  • The authorization request date as a HTTP header string value.

    Returns undefined | string

signingKeyExpirationDate

  • get signingKeyExpirationDate(): undefined | Date

  • Get the saved signing key expiration date.

    This will return the expiration date the signing key saved via key() or saveSigningKey().

    Returns undefined | Date

signingKeyValid

  • get signingKeyValid(): boolean

  • Test if a signing key is present and not expired.

    Returns boolean

useSnDate

  • get 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.

    Returns boolean

  • set useSnDate(enabled): void

  • Parameters

    • enabled: boolean

    Returns void

Methods

Private #canonicalSignedHeaderNames

  • #canonicalSignedHeaderNames(sortedLowercaseHeaderNames): string

  • Compute the canonical signed header names value from an array of HTTP header names.

    Parameters

    • sortedLowercaseHeaderNames: string[]

      the sorted, lower-cased HTTP header names to include

    Returns string

    the canonical signed header names string value

Private #computeCanonicalRequestData

  • #computeCanonicalRequestData(sortedLowercaseHeaderNames): string

  • Compute the canonical request data that will be included in the data to sign with the request, using a specific set of HTTP header names to sign.

    Parameters

    • sortedLowercaseHeaderNames: string[]

      the sorted, lower-cased HTTP header names to sign with the request

    Returns string

    the canonical request data

build

  • Compute a HTTP Authorization header value from the configured properties on the builder, computing a new signing key based on the configured Net.AuthorizationV2Builder#date.

    Parameters

    • tokenSecret: string

      the secret to sign the authorization with

    Returns string

    the SNWS2 HTTP Authorization header value

buildCanonicalRequestData

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

    Returns string

    the canonical request data

buildWithKey

  • Compute a HTTP Authorization header value from the configured properties on the builder, using the provided signing key.

    This method does not save the signing key for future use in this builder instance (see key() for that).

    Parameters

    • signingKey: WordArray

      the key to sign the computed signature data with

    Returns string

    the SNWS2 HTTP Authorization header value

buildWithSavedKey

  • Compute a HTTP Authorization header value from the configured properties on the builder, using a signing key configured from a previous call to saveSigningKey() or key().

    Returns string

    the SNWS2 HTTP Authorization header value.

    Throws

    Error if a saved signing key is not configured

canonicalContentSHA256

  • Get the canonical request content SHA256 digest, hex encoded.

    Returns string

    the hex-encoded SHA256 digest of the request content

canonicalHeaderNames

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

    Returns string[]

    the sorted, lower-cased HTTP header names to include

canonicalHeaders

  • Compute the canonical HTTP headers string value.

    Parameters

    • sortedLowercaseHeaderNames: string[]

      the sorted, lower-cased HTTP header names to include

    Returns string

    the canonical headers string value

canonicalQueryParameters

  • Compute the canonical query parameters.

    Returns string

    the canonical query parameters string value

computeContentDigest

  • Compute the SHA-256 digest of the request body content and configure the result on this builder.

    This method will compute the digest and then save the result via the contentSHA256() method. In addition, it will set the Digest HTTP header value via header(). This means you must also pass the Digest HTTP header with the request. After calling this method, you can retrieve the Digest HTTP header value via the httpHeadersproperty.

    Parameters

    • content: string

      the request body content to compute a SHA-256 digest value from

    Returns AuthorizationV2Builder

    this object

computeSignatureData

  • Compute the data to be signed by the signing key.

    The signature data takes this form:

    SNWS2-HMAC-SHA256
    20170301T120000Z
    Hex(SHA256(canonicalRequestData))

    Parameters

    Returns string

    the data to sign

computeSigningKey

  • Compute the signing key, from a secret key and based on the configured date().

    This method does not save the signing key for future use in this builder instance (see saveSigningKey() for that). Use this method if you want to compute a signing key that you can later pass to buildWithKey() on some other builder instance. Signing keys are valid for a maximum of 7 days, granular to whole days only. To make a signing key expire in fewer than 7 days, configure a date() value in the past before calling this method.

    Parameters

    • secretKey: string

      the secret key string

    Returns WordArray

    the computed key

contentSHA256

contentType

date

header

headers

host

key

  • Get or set the signing key.

    Use this method to save an existing signing key, for example one received via a refresh request. The date parameter is used to track the expirataion date of the key, as reported by the signingKeyValid property.

    If you have an actual token secret value, use the saveSigningKey() method to save it rather than this method.

    Returns undefined | WordArray

    when called as a getter the current saved signing key value, otherwise this object

    See

    Net.AuthorizationV2Builder#signingKeyExpirationDate

  • Parameters

    • key: WordArray
    • Optional date: Date

    Returns AuthorizationV2Builder

method

path

queryParams

reset

saveSigningKey

  • 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 build() can be called later. The signing date will be set to whatever date is currently configured via date(), which defaults to the current time for newly created builder instances.

    If you have an externally computed signing key, such as one returned from a token refresh API call, use the key() method to save it rather than this method. If you want to compute the signing key, without caching it on this builder, use the computeSigningKey() method rather than this method.

    Parameters

    • tokenSecret: string

      the secret to sign the digest with

    Returns AuthorizationV2Builder

    this object

signedHttpHeaders

snDate

url

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

    Parameters

    • url: string

      the URL value to use

    • Optional ignoreHost: boolean

      if true then do not set the host() from the given URL; this can be useful when you do not want to override the configured environment host

    Returns AuthorizationV2Builder

    this object

Settings

Member Visibility

Theme

On This Page

Generated using TypeDoc