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()
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>
* 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)
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.
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
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.
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.