@varlock/keeper-plugin

@varlock/keeper-plugin

This package is a Varlock plugin that enables loading secrets from Keeper Security vaults via the Keeper Secrets Manager SDK.

Features

• 🔐 Fetch individual secrets by record UID, title, or Keeper notation
• 🏷️ Access standard and custom fields (password, login, URL, notes, etc.)
• 🔑 Secure authentication via base64-encoded Secrets Manager configuration
• 📦 Multiple instance support for different vaults or applications
• ✅ Built-in validation for Keeper Secrets Manager config tokens

Installation

# npm
npm install @varlock/keeper-plugin

# pnpm
pnpm add @varlock/keeper-plugin

# yarn
yarn add @varlock/keeper-plugin

# bun
bun add @varlock/keeper-plugin

Prerequisites

You need a Keeper Secrets Manager application set up in your Keeper vault:

• In the Keeper Admin Console, create a Secrets Manager Application
• Share a folder with the application
• Generate a one-time access token
• Use the KSM CLI to initialize a config:

pip install keeper-secrets-manager-cli
ksm profile init <one-time-token>
ksm profile export --format json | base64

• Store the base64-encoded config as the KSM_CONFIG environment variable

Setup

Basic setup

# @plugin(@varlock/keeper-plugin)
# @initKeeper(token=$KSM_CONFIG)
# ---

# @type=keeperSmToken @sensitive @internal
KSM_CONFIG=

Multiple instances

# @plugin(@varlock/keeper-plugin)
# @initKeeper(token=$KSM_CONFIG_PROD, id=prod)
# @initKeeper(token=$KSM_CONFIG_DEV, id=dev)
# ---

# @type=keeperSmToken @sensitive @internal
KSM_CONFIG_PROD=

# @type=keeperSmToken @sensitive @internal
KSM_CONFIG_DEV=

Loading secrets

By record UID (defaults to password field)

# fetches the "password" field from the record
DB_PASSWORD=keeper("XXXXXXXXXXXXXXXXXXXX")

By record UID with a specific field

# fetch the "login" standard field
DB_USER=keeper("XXXXXXXXXXXXXXXXXXXX#login")

# fetch a custom field by label
API_KEY=keeper("XXXXXXXXXXXXXXXXXXXX#API_KEY")

# or use the named field parameter
DB_HOST=keeper("XXXXXXXXXXXXXXXXXXXX", field="host")

Using Keeper notation

The plugin supports Keeper's notation syntax for more advanced access patterns:

# standard field by type
DB_PASS=keeper("XXXX/field/password")

# standard field by label
DB_LOGIN=keeper("XXXX/field/login")

# custom field by label
MY_SECRET=keeper("XXXX/custom_field/MySecretLabel")

# by record title instead of UID
API_KEY=keeper("My API Keys/field/password")

With named instances

# first arg is instance id, second is the secret reference
PROD_SECRET=keeper(prod, "XXXX/field/password")
DEV_SECRET=keeper(dev, "YYYY#password")

Reference

Root decorators

@initKeeper()

Initialize a Keeper Secrets Manager plugin instance.

Parameter	Type	Required	Description
token	string	yes	Base64-encoded Secrets Manager config (typically from $KSM_CONFIG)
cacheTtl	string | number	no	Cache resolved values from keeper() for the provided TTL ("5m", "1h", "1d", or "forever" to cache until manually cleared); set to false (or an empty string) to disable caching
id	string	no	Instance identifier for multiple configurations (defaults to _default)

Data types

keeperSmToken

A sensitive string type for Keeper Secrets Manager configuration tokens. Validates that the value is a valid base64-encoded JSON string.

Resolver functions

keeper(reference) / keeper(instanceId, reference)

Fetch a single secret field from Keeper.

Arguments:

Position	Type	Required	Description
1	string	yes (if no instanceId)	Secret reference (see formats below)
1, 2	string, string	for named instances	Instance ID, then secret reference

Named parameters:

Parameter	Type	Required	Description
field	string	no	Explicit field type/label to extract

Reference formats:

Format	Description	Example
<uid>	Record UID (defaults to password field)	keeper("XXXX")
<uid>#<field>	Record UID with field selector	keeper("XXXX#login")
<uid>/field/<type>	Keeper notation (standard field)	keeper("XXXX/field/password")
<uid>/custom_field/<label>	Keeper notation (custom field)	keeper("XXXX/custom_field/API_KEY")
<title>/field/<type>	Keeper notation (by title)	keeper("My Record/field/password")

Keeper Secrets Manager setup guide

Step 1: Create a Secrets Manager Application

• Log in to the Keeper Admin Console
• Navigate to Secrets Manager → Applications
• Click Create Application
• Give it a descriptive name (e.g., "varlock-dev")

Step 2: Share folders

• In your Keeper vault, right-click the folder containing your secrets
• Select Share Folder
• Share it with your Secrets Manager application

Step 3: Generate a one-time access token

• In the application settings, click Add Device
• Copy the one-time access token

Step 4: Initialize and export the config

# Install the KSM CLI
pip install keeper-secrets-manager-cli

# Initialize with the one-time token
ksm profile init <one-time-token>

# Export as base64 for use as an env var
ksm profile export --format json | base64

Step 5: Set up your schema

# @plugin(@varlock/keeper-plugin)
# @initKeeper(token=$KSM_CONFIG)
# ---

# @type=keeperSmToken @sensitive @internal
KSM_CONFIG=

# Your secrets
DB_PASSWORD=keeper("your-record-uid/field/password")
API_KEY=keeper("your-record-uid/custom_field/api_key")

Troubleshooting

"Failed to parse Keeper config token"

The KSM_CONFIG value must be a valid base64-encoded JSON string. Regenerate it:

ksm profile export --format json | base64

"Keeper access denied"

• Verify the Secrets Manager application has not been revoked
• Check that the shared folder permissions are still active
• The one-time token may have expired before being used — generate a new one

"Record not found"

• Verify the record UID or title is correct
• Ensure the record is in a folder shared with the Secrets Manager application
• Record UIDs are case-sensitive

"Field not found in record"

• Check available field types with keeper("uid/field/password")
• Custom fields use the label: keeper("uid/custom_field/My Label")
• Standard field types include: login, password, url, oneTimeCode, note

Links

• Varlock Documentation
• Keeper Security
• Keeper Secrets Manager Docs
• JavaScript SDK Docs
• KSM CLI Docs