@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:

1. In the Keeper Admin Console, create a Secrets Manager Application
2. Share a folder with the application
3. Generate a one-time access token
4. 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

5. 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
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
KSM_CONFIG_PROD=

# @type=keeperSmToken @sensitive
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) | | 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

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

Step 2: Share folders

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

Step 3: Generate a one-time access token

1. In the application settings, click Add Device
2. 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
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