All pages
Powered by GitBook
1 of 1

JavaScript SDK

Detailed Javascript SDK docs for Keeper Secrets Manager

Download and Installation

Install with NPM

npm install @keeper-security/secrets-manager-core

Source Code

Find the JavaScript source code in the GitHub repository

Using the SDK

Initialize Storage

Using token only to generate a new config (for later usage) requires at least one read operation to bind the token and fully populate config.json

In order to retrieve secrets, you must first initialize the local storage on your machine.

initializeStorage(storage: KeyValueStorage, clientKey: String? = null, hostName: String? = null)

Parameter

Type

Required

Default

Description

storage

KeyValueStorage

Yes

storage location

clientKey

string

Optional

null

token for connecting with Keeper Secrets Manager

hostName

string

Optional

null

server location to get secrets. If nothing is passed, will use keepersecurity.com (US)

Example Usage

const { getSecrets, initializeStorage, localConfigStorage } = require('@keeper-security/secrets-manager-core')

const getKeeperRecords = async () => {

    // oneTimeToken is used only once to initialize the storage
    // after the first run, subsequent calls will use ksm-config.txt
    const oneTimeToken = "<One Time Access Token>";
    
    const storage = localConfigStorage("ksm-config.json")
    
    await initializeStorage(storage, oneTimeToken)
    // Using token only to generate a config (for later usage)
    // requires at least one access operation to bind the token
    //await getSecrets({storage: storage})
    
    const {records} = await getSecrets({storage: storage})
    console.log(records)

    const firstRecord = records[0]
    const firstRecordPassword = firstRecord.data.fields.find(x => x.type === 'password')
    console.log(firstRecordPassword.value[0])
}

getKeeperRecords().finally()

Retrieve Secrets

getSecrets(options: SecretsManagerOptions, recordsFilter: List<String> = emptyList()): KeeperSecrets

Parameter

Type

Required

Default

Description

storage

KeyValueStorage

Yes

Storage location

recordsFilter

string[]

Optional

Empty List

Record UIDs to get

Response

Type: KeeperSecrets

Object containing all Keeper records, or records that match the given filter criteria

Example Usage

Retrieve all Secrets

const storage = inMemoryStorage() // see initialization example
val secrets = getSecrets(storage)

Retrieve Secrets by Title

// get all matching records
getSecretsByTitle = async (options: SecretManagerOptions, recordTitle: string): Promise<KeeperRecord[]>

// get only the first matching record
getSecretByTitle = async (options: SecretManagerOptions, recordTitle: string): Promise<KeeperRecord>
Parameter
Type
Required
Description

options

SecretsManagerOptions

Yes

Preconfigured options

recordTitle

string

Yes

Record title to search for

Example Usage

const {
    getSecretByTitle,
    localConfigStorage,
} = require('@keeper-security/secrets-manager-core')

const getKeeperRecord = async () => {
    const options = { storage: localConfigStorage("ksm-config.json") }
    const myCredential = await getSecretByTitle(options, "My Credential")
}

getKeeperRecord().finally()

Retrieve Values From a Secret

Retrieve a Password

secret.data.fields.find(x => x.type === 'password')
const { getSecrets, initializeStorage, localConfigStorage } = require('@keeper-security/secrets-manager-core')

const getKeeperRecords = async () => {
    const storage = localConfigStorage("ksm-config.json")
    // get records
    const {records} = await getSecrets({storage: storage})
    // get password from first record
    const firstRecord = records[0]
    const firstRecordPassword = firstRecord.data.fields.find(x => x.type === 'password')
}

Fields are found by type, for a list of field types see the Record Types documentation.

Retrieve other Fields with Keeper Notation

getValue(secrets: KeeperSecrets, query: string): any
const {
    getSecrets,
    localConfigStorage,
    getValue
} = require('@keeper-security/secrets-manager-core')

const getKeeperRecords = async () => {
    const options = { storage: localConfigStorage("ksm-config.json") }
    
    // get secrets
    const secrets = await getSecrets(options)

    // get login with dot notation
    const loginValue = getValue(secrets, 'RECORD_UID/field/login')
}

See Keeper Notation documentation to learn about Keeper Notation format and capabilities

Parameter

Type

Required

Default

Description

secrets

KeeperSecrets

Yes

Secrets to query

query

string

Yes

Keeper Notation query

* The record UID in the notation query must be for a secret passed in the secrets parameter or nothing will be found by the query

Returns

Type: any

The value of the field at the location specified by the dot notation query if any, otherwise undefined.

Retrieve a TOTP Code

getTotpCode(url: string): string
const { 
    getSecrets, 
    localConfigStorage, 
    getTotpCode, 
    getValue} = require('@keeper-security/secrets-manager-core')

const getKeeperRecords = async () => {
    const options = { storage: localConfigStorage("ksm-config.json") }

    // get secrets
    const secrets = await getSecrets(options)

    // get login with dot notation
    const totpUri = getValue(secrets,'RECORD_UID/field/oneTimeCode')

    //get TOTP code
    const totp = await getTotpCode(totpUri)
}

See Keeper Notation documentation to learn about Keeper Notation format and capabilities

Parameter

Type

Required

Default

Description

url

string

Yes

TOTP Url

* The record UID in the notation query must be for a secret passed in the secrets parameter or nothing will be found by the query

Returns

Type: any

The value of the field at the location specified by the dot notation query if any, otherwise undefined.

Update a Secret

Record update commands don't update local record data on success (esp. updated record revision) so any consecutive updates to an already updated record will fail due to revision mismatch. Make sure to reload all updated records after each update batch.

updateSecret(options, record)
const { 
    getSecrets, 
    localConfigStorage, 
    updateSecret} = require('@keeper-security/secrets-manager-core')

const storage = localConfigStorage("ksm-config.json")

// get records
const {records} = await getSecrets({storage: storage})

// get the first record
const recordToUpdate = records[0]

// set new record title and notes
recordToUpdate.data.title = 'New Title'
recordToUpdate.data.notes = "New Notes"

// save record changes
await updateSecret(options, recordToUpdate)
const { 
    getSecrets, 
    localConfigStorage, 
    updateSecret,
    completeTransaction,
    UpdateTransactionType,
    SecretManagerOptions
} = require('@keeper-security/secrets-manager-core')

// get records
const options = { storage: localConfigStorage("ksm-config.json") }
const {records} = await getSecrets(options)

// rotate password on the first record
const secret = records[0]
const password = secret.data.fields.find(x => x.type === "password")
password.value[0] = "MyNewPassword"

//start a transaction to update record in vault
await updateSecret(options, secret, UpdateTransactionType.Rotation)

// rotate password on remote host
const success = rotateRemoteSshPassword("MyNewPassword");

// complete the transaction - commit or rollback
const rollback = !success
await completeTransaction(options, secret.recordUid, rollback)

Parameter

Type

Required

Default

Description

options

SecretManagerOptions

Yes

record

KeeperRecord

Yes

Returns

Type: Promise<void>

Generate a Random Password

generatePassword(length, lowercase, uppercase, digits, specialCharacters)
const { 
    getSecrets, 
    localConfigStorage, 
    updateSecret, 
    generatePassword } = require('@keeper-security/secrets-manager-core')

// generate a random password
let newRandomPwd = await generatePassword()

const storage = localConfigStorage("ksm-config.json")
const {records} = await getSecrets({storage: storage})

// get the first record
const recordToUpdate = records[0]

// Find the field with the type "password"
const recordToUpdatePasswordField = recordToUpdate.data.fields.find(x => x.type === 'password')

// set new value to the password field
recordToUpdatePasswordField.value[0] = newRandomPwd

await updateSecret({storage: storage}, recordToUpdate)
Parameter
Type
Required
Default

length

int

Optional

64

lowercase

int

Optional

0

uppercase

int

Optional

0

digits

int

Optional

0

specialCharacters

int

Optional

0

Each parameter indicates the min number of a type of character to include. For example, 'uppercase' indicates the minimum number of uppercase letters to include.

Returns

Type: String

Download a File

downloadFile(file: KeeperFile): ByteArray

Parameter

Type

Required

Default

Description

file

KeeperFile

Yes

File to download

Response

Type: Promise<Uint8Array

Bytes of file for download

Download a Thumbnail

downloadThumbnail(file: KeeperFile): ByteArray

Parameter

Type

Required

Default

Description

file

KeeperFile

Yes

File with thumbnail to download

Response

Type: Promise<Uint8Array>

Bytes of thumbnail for download

Upload a File

Upload File:

uploadFile = async (options: SecretManagerOptions, ownerRecord: KeeperRecord, file: KeeperFileUpload): Promise<string>

Parameter
Type
Required
Description

options

SecretsManagerOptions

Yes

Storage and query configuration

ownerRecord

KeeperRecord

Yes

The record to attach the uploaded file to

file

KeeperFileUpload

Yes

The File to upload

Creating the Keeper File Upload Object:

type KeeperFileUpload = {
    name: string
    title: string
    type?: string
    data: Uint8Array
}
Parameter
Type
Required
Description

name

string

Yes

What the name of the file will be in Keeper once uploaded

title

string

Yes

What the title of the file will be in Keeper once uploaded

type

string

Optional

The mime type of data in the file. 'application/octet-stream' will be used if nothing is given

data

Uint8Array

Yes

File data as bytes

Example Usage

// get record to attach file to
const {records} = await getSecrets({storage: storage}, ['XXX'])
const ownerRecord = records[0]

// get file data to upload
const fileData = fs.readFileSync('./assets/my-file.json')

// upload file to selected record
await uploadFile(options, ownerRecord, {
    name: 'my-file.json',
    title: 'Sample File',
    type: 'application/json',
    data: fileData
})

Create a Secret

Prerequisites:

  • Shared folder UID

    • Shared folder must be accessible by the Secrets Manager Application

    • You and the Secrets Manager application must have edit permission

    • There must be at least one record in the shared folder

  • Created records and record fields must be formatted correctly

    • See the documentation for expected field formats for each record type

  • TOTP fields accept only URL generated outside of the KSM SDK

  • After record creation, you can upload file attachments using uploadFile

createSecret(options, folderUid, record)
Parameter
Type
Required
Default

options

SecretManagerOptions

Yes

folderUid

string

Yes

record

JSON Object

Yes

createSecret2(options, createOptions, record)
Parameter
Type
Required
Default

options

SecretManagerOptions

Yes

createOptions

CreateOptions

Yes

record

JSON Object

Yes

This example creates a login type record with a login value and a generated password.

Replace '[FOLDER UID]' in the example with the UID of a shared folder that your Secrets Manager has access to.

let newRec = {
    "title": "Sample KSM Record: JavaScript",
    "type": "login",
    "fields": [
        { "type": "login",    "value": [ "username@email.com" ] },
        { "type": "password", "value": [ await generatePassword() ] }
    ],
    "notes": "This is a JavaScript record creation example"
}

let recordUid = await createSecret(options, folderUid, newRec)

This example creates a record with a custom record type.

Replace '[FOLDER UID]' in the example with the UID of a shared folder that your Secrets Manager has access to.

let newRec = {
    "title": "Sample Custom Type KSM Record: JavaScript",
    "type": "Custom Login",
    "fields": [
        {
            "type": "host",
            "label": "My Custom Host lbl",
            "value": [ {"hostName": "127.0.0.1", "port": "8080"} ],
            "required": true,
            "privacyScreen": false
        },
        {
            "type": "login",
            "label": "My Custom Login lbl",
            "value": [ "login@email.com" ],
            "required": true,
            "privacyScreen": false
        },
        {
            "type": "password",
            "label": "My Custom Password lbl",
            "value": [ await generatePassword() ],
            "required": true,
            "privacyScreen": false
        },
        {
            "type": "url",
            "label": "My Login Page",
            "value": [ "http://localhost:8080/login" ],
            "required": true,
            "privacyScreen": false
        },
        {
            "type": "securityQuestion",
            "label": "My Question 1",
            "value": [ {
                "question": "What is one plus one (write just a number)",
                "answer": "2"
            } ],
            "required": true,
            "privacyScreen": false
        },
        {
            "type": "phone",
            "value": [{
                "region": "US",
                "number": "510-444-3333",
                "ext": "2345",
                "type": "Mobile"
            }],
            "label": "My Phone Number"
        },
        {
            "type": "date",
            "value": [ 1641934793000 ],
            "label": "My Date Lbl",
            "required": true,
            "privacyScreen": false
        },
        {
            "type": "name",
            "value": [{
                "first": "John",
                "middle": "Patrick",
                "last": "Smith"
            }],
            "label": "My Custom Name lbl",
            "required": true,
            "privacyScreen": false
        },
        {
            "type": "oneTimeCode",
            "label": "My TOTP",
            "value": ["otpauth://totp/Example:alice@google.com?secret=JBSWY3DPEHPK3PXP&issuer=Example"],
            "required": true,
            "privacyScreen": false
        }
    ],
    "custom": [
        {
            "type": "phone",
            "value": [{
                "region": "US",
                "number": "(510) 123-3456"
            }],
            "label": "My Custom Phone Lbl 1"
        },
        {
            "type": "phone",
            "value": [ {
                "region": "US",
                "number": "510-111-3333",
                "ext": "45674",
                "type": "Mobile" } ],
            "label": "My Custom Phone Lbl 2"
        }
    ],
    "notes": "\tThis custom type record was created\n\tvia KSM Katacoda JavaScript Example"
}

let recordUid = await createSecret(options, "[FOLDER UID]", newRec)

Delete a Secret

The JavaScript KSM SDK can delete records in the Keeper Vault.

deleteSecret(smOptions, recordUids);
Parameter
Type
Required

smOptions

SecretManagerOptions

Yes

recordUids

string[]

Yes

// setup secrets manager
const smOptions = { storage: localConfigStorage("ksm-config.json") 

// delete a specific secret by record UID
await deleteSecret(smOptions, ["EG6KdJaaLG7esRZbMnfbFA"]);

Caching

To protect against losing access to your secrets when network access is lost, the JavaScript SDK allows caching of secrets to the local machine in an encrypted file.

Add queryFunction: cachingPostFunction to SecretManagerOptions

Example usage:

const options: SecretManagerOptions = {    
    storage: kvs,
    queryFunction: cachingPostFunction // Import `cachingPostFunction`
}

Folders

Folders have full CRUD support - create, read, update and delete operations.

Read Folders

Downloads full folder hierarchy.

getFolders = async (options: SecretManagerOptions): Promise<KeeperFolder[]>

Response

Type: KeeperFolder[]

Example Usage

const storage = localConfigStorage("ksm-config.json")
const folders = await getFolders({storage: storage})

Create a Folder

Requires CreateOptions and folder name to be provided. The folder UID parameter in CreateOptions is required - UID of a shared folder, while sub-folder UID is optional and if missing new regular folder is created directly under the parent (shared folder). There's no requirement for the sub-folder to be a direct descendant of the parent shared folder - it could be many levels deep.

createFolder = async (options: SecretManagerOptions, createOptions: CreateOptions, folderName: string): Promise<string>
Parameter
Type
Required
Description

options

SecretsManagerOptions

Yes

Preconfigured options

createOptions

CreateOptions

Yes

The parent and sub-folder UIDs

folderName

string

Yes

The Folder name

type CreateOptions = {
    folderUid: string
    subFolderUid?: string
}

Example Usage

const storage = localConfigStorage("ksm-config.json")
const folderUid = await createFolder({storage: storage}, {folderUid: "[PARENT_SHARED_FOLDER_UID]"}, "new_folder")

Update a Folder

Updates the folder metadata - currently folder name only.

updateFolder = async (options: SecretManagerOptions, folderUid: string, folderName: string): Promise<void>
Parameter
Type
Required
Description

options

SecretsManagerOptions

Yes

Preconfigured options

folderUid

string

Yes

The folder UID

folderName

string

Yes

The new folder name

Example Usage

const storage = localConfigStorage("ksm-config.json")
await updateFolder({storage: storage}, "[FOLDER_UID]", "new_folder_name")

Delete Folders

Removes a list of folders. Use forceDeletion flag to remove non-empty folders.

When using forceDeletion avoid sending parent with its children folder UIDs. Depending on the delete order you may get an error - ex. if parent force-deleted child first. There's no guarantee that list will always be processed in FIFO order.

Any folders UIDs missing from the vault or not shared to the KSM Application will not result in error.

deleteFolder = async (options: SecretManagerOptions, folderUids: string[], forceDeletion?: boolean): Promise<SecretsManagerDeleteResponse>
Parameter
Type
Required
Default
Description

options

SecretsManagerOptions

Yes

Preconfigured options

folderUids

string[]

Yes

The folder UID list

forceDeletion

bool

No

false

Force deletion of non-empty folders

Example Usage

const storage = localConfigStorage("ksm-config.json")
await deleteFolder({storage: storage}, ["[FOLDER_UID1]", "[FOLDER_UID2]"], true)