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;