Credential Management for WCH CLI

Utility library to manage credentials for use with WCH CLI projects.

Installation

Local install for use from an NPM script:

npm install --save-dev @acoustic-content-sdk/cli-credentials

Class documentation

Refer to the API documentation.

Credential Management

The credentials used to access a tenant can be stored securely on your development machine. Depending on the operating system, use one of the following options.

Credential Management (Windows)

Under Windows use the Credential Manager to store your credentials for WCH. You can start the credential manager by navigating to Control Panel\User Accounts and Family Safety\Credential Manager. Create a new Generic Credential. As Internet or network address choose the API URL from WCH, make sure end the URL with a trailing slash. Enter your WCH username and password and hit OK.

Credential Management (macOS)

Under macOS use the Keychain Access to store your credentials for WCH. Use the API URL from WCH as the name of the credenitial, this will automatically make it an internet credential. Enter your WCH username and password and hit OK.

Credential Management (Linux)

Under Linux the credentials are read from the ${home}/.ibm-wch-sdk-cli/.credentials file. Use the store credentials command to securely persist the credentials in this file.

Credential Storage

Stores a user name and password WCH in the file ${home}/.ibm-wch-sdk-cli/.credentials. The password is encrypted using the private SSH key found in ${home}/.ssh/id_rsa. This command has been designed to work in a Unix environment, but it will also for for Windows provided an SSH key exists at the specified location. Disclaimer this method requires password free access to the SSH key.

Note

If the file ${home}/.ssh/id_rsa does not exist, you can create one using the following shell command:

ssh-keygen -t rsa -q -f ~/.ssh/id_rsa -P ""

Usage

The module exports the following functions to work with credentials:

wchGetCredentials

Reads the credentials for the given API URL.

function wchGetCredentials(
  aApiUrl: string,
  aOptions?: Options
): Promise<Credentials>;

• aApiUrl: the API URL for your tenant
• aOptions: optional options to control logging

wchStoreCredentials

Stores the given credentials in the ${home}/.ibm-wch-sdk-cli/.credentials file in every environment (including Windows).

function wchStoreCredentials(
  aWchToolsOptions: WchToolsOptions,
  aOptions?: Options
): Promise<string>;

• aWchToolsOptions: credentials and API URL
• aOptions: optional options to control logging

wchRemoveCredentials

Removes the credentials for the given API URL from the ${home}/.ibm-wch-sdk-cli/.credentials file in every environment (including Windows).

function wchRemoveCredentials(
  aApiUrl: string,
  aOptions?: Options
): Promise<string>;

• aApiUrl: the API URL for your tenant
• aOptions: optional options to control logging

isValidPassword

Checks if a password is valid syntactically

function isValidPassword(aValue: any): aValue is string;

isValidUrl

Checks if a URL is valid syntactically

function isValidUrl(aValue: any): aValue is string;

isValidUserName

Checks if a username is valid syntactically. This is the case if it is either an email or the term apikey.

function isValidUserName(aValue: any): aValue is string;

isValidCredentials

Checks if the credentials object is valid syntactically.

function isValidCredentials(aCred: any): aCred is Credentials;

isValidApiUrl

Checks if a string is a valid API URL by trying to access well known API routes.

function isValidApiUrl(aValue: any): Promise<boolean>;

isValidWchToolsOptions

Checks if the WchToolsOptions combination of API URL, username and password is valid by trying to login to the targeted server.

function isValidWchToolsOptions(
  aCredentials: WchToolsOptions
): Promise<boolean>;

Home > @acoustic-content-sdk/cli-credentials

cli-credentials package

Functions

| Function | Description | | --- | --- | | isValidApiUrl(aValue) | Checks if the URL is a valid WCH API URL by making a test call | | isValidPassword(aValue) | Checks if a password is valid | | isValidUrl(aValue) | Checks if the url is syntactically a valid URL | | isValidUserName(aValue) | Checks if a username is valid, i.e. either an email or the term 'apikey' | | isValidWchToolsOptions(aCredentials) | Validates the credentials by trying to login | | wchGetCredentials(aApiUrl, aOptions) | Reads the credentials for the given API URL | | wchRemoveCredentials(aApiUrl, aOptions) | | | wchStoreCredentials(aWchToolsOptions, aOptions) | |

Interfaces

| Interface | Description | | --- | --- | | Credentials | WCH credentials | | Options | Contextual options | | WchToolsOptions | Extension of the credentials to also carry the API URL that the credentials apply to |

Variables

| Variable | Description | | --- | --- | | VERSION | Version and build number of the package |

Type Aliases

| Type Alias | Description | | --- | --- | | Logger | Simple logger interface that this library used to print debug logs |

Home > @acoustic-content-sdk/cli-credentials > isValidApiUrl

isValidApiUrl() function

Checks if the URL is a valid WCH API URL by making a test call

Signature:

export declare function isValidApiUrl(aValue: any): Promise<boolean>;

Parameters

| Parameter | Type | Description | | --- | --- | --- | | aValue | any | |

Returns:

Promise<boolean>

true if the URL is valid, else false

Home > @acoustic-content-sdk/cli-credentials > isValidPassword

isValidPassword() function

Checks if a password is valid

Signature:

export declare function isValidPassword(aValue: any): aValue is string;

Parameters

| Parameter | Type | Description | | --- | --- | --- | | aValue | any | the value to test |

Returns:

aValue is string

true if the password is valid, else false

Home > @acoustic-content-sdk/cli-credentials > isValidUrl

isValidUrl() function

Checks if the url is syntactically a valid URL

Signature:

export declare function isValidUrl(aValue: any): aValue is string;

Parameters

| Parameter | Type | Description | | --- | --- | --- | | aValue | any | the value |

Returns:

aValue is string

true if the value is a valid URL, else false

Home > @acoustic-content-sdk/cli-credentials > isValidUserName

isValidUserName() function

Checks if a username is valid, i.e. either an email or the term 'apikey'

Signature:

export declare function isValidUserName(aValue: any): aValue is string;

Parameters

| Parameter | Type | Description | | --- | --- | --- | | aValue | any | the value to test |

Returns:

aValue is string

true if the name is valid, else false

Home > @acoustic-content-sdk/cli-credentials > isValidWchToolsOptions

isValidWchToolsOptions() function

Validates the credentials by trying to login

Signature:

export declare function isValidWchToolsOptions(aCredentials: WchToolsOptions): Promise<boolean>;

Parameters

| Parameter | Type | Description | | --- | --- | --- | | aCredentials | WchToolsOptions | the credentials |

Returns:

Promise<boolean>

true if the credentials were correct, else false

Home > @acoustic-content-sdk/cli-credentials > wchGetCredentials

wchGetCredentials() function

Reads the credentials for the given API URL

Signature:

export declare function wchGetCredentials(aApiUrl: string, aOptions?: Options): Promise<Credentials>;

Parameters

| Parameter | Type | Description | | --- | --- | --- | | aApiUrl | string | the API URL | | aOptions | Options | options for debugging and logging |

Returns:

Promise<Credentials>

a promise of the loaded credentials

Home > @acoustic-content-sdk/cli-credentials > wchRemoveCredentials

wchRemoveCredentials() function

Signature:

declare function _removeCredentials(aApiUrl: string, aOptions?: Options): Promise<string>;

Parameters

| Parameter | Type | Description | | --- | --- | --- | | aApiUrl | string | | | aOptions | Options | |

Returns:

Promise<string>

Home > @acoustic-content-sdk/cli-credentials > wchStoreCredentials

wchStoreCredentials() function

Signature:

declare function _writeCredentials(aWchToolsOptions: WchToolsOptions, aOptions?: Options): Promise<string>;

Parameters

| Parameter | Type | Description | | --- | --- | --- | | aWchToolsOptions | WchToolsOptions | | | aOptions | Options | |

Returns:

Promise<string>

Home > @acoustic-content-sdk/cli-credentials > Credentials

Credentials interface

WCH credentials

Signature:

export interface Credentials 

Properties

| Property | Type | Description | | --- | --- | --- | | password | string | The WCH password | | username | string | The WCH username, typically an email or the string 'apikey' |

Home > @acoustic-content-sdk/cli-credentials > Options

Options interface

Contextual options

Signature:

export interface Options 

Properties

| Property | Type | Description | | --- | --- | --- | | debug | boolean | If set to true, print debug logs | | logger | Logger | If provided, the logger to be used to print debug logs |

Home > @acoustic-content-sdk/cli-credentials > WchToolsOptions

WchToolsOptions interface

Extension of the credentials to also carry the API URL that the credentials apply to

Signature:

export interface WchToolsOptions extends Credentials 

Properties

| Property | Type | Description | | --- | --- | --- | | baseUrl | string | The WCH AP URL |

Home > @acoustic-content-sdk/cli-credentials > VERSION

VERSION variable

Version and build number of the package

Signature:

VERSION: {
    version: {
        major: string;
        minor: string;
        patch: string;
        branch: string;
    };
    build: Date;
}

Home > @acoustic-content-sdk/cli-credentials > Logger

Logger type

Simple logger interface that this library used to print debug logs

Signature:

export declare type Logger = (...optionalParams: any[]) => void;

Home > @acoustic-content-sdk/cli-credentials > Credentials > password

Credentials.password property

The WCH password

Signature:

password: string;

Home > @acoustic-content-sdk/cli-credentials > Credentials > username

Credentials.username property

The WCH username, typically an email or the string 'apikey'

Signature:

username: string;

Home > @acoustic-content-sdk/cli-credentials > Options > debug

Options.debug property

If set to true, print debug logs

Signature:

debug?: boolean;

Home > @acoustic-content-sdk/cli-credentials > Options > logger

Options.logger property

If provided, the logger to be used to print debug logs

Signature:

logger?: Logger;

Home > @acoustic-content-sdk/cli-credentials > WchToolsOptions > baseUrl

WchToolsOptions.baseUrl property

The WCH AP URL

Signature:

baseUrl: string;