Credential vault

This pack gives an agent tools to store, retrieve, list, rotate, and import credentials scoped by platform and key. It uses Node.js crypto for AES-256-GCM encryption and keeps credentials in memory.

Installation

npm install @framers/agentos-ext-credential-vault

Peer dependency: @framers/agentos with range >=0.10.40.

Usage

import { AgentOS } from '@framers/agentos';

const agentos = await AgentOS.create({
  extensionManifest: {
    packs: [
      {
        package: '@framers/agentos-ext-credential-vault',
        options: {
          passphrase: process.env.CREDENTIAL_VAULT_PASSPHRASE,
        },
      },
    ],
  },
});

Configuration

Passphrase resolution checks options.passphrase, the selected secrets map's credential-vault.passphrase, and CREDENTIAL_VAULT_PASSPHRASE, then uses the default. options.secrets takes precedence over context secrets; the maps are not merged. Resolution uses nullish coalescing, so an empty string passphrase is accepted.

Tools

credentialsSet

credentialsGet

credentialsList

credentialsRotate

credentialsImport

Notes

• Activation initializes the vault. Before activation and after deactivation, tools return success: false with "CredentialVaultService not initialized". Deactivation clears stored credentials.
• The passphrase derives the encryption key through scryptSync with the fixed salt agentos-credential-vault-salt. Each stored value uses a random initialization vector. Missing passphrase configuration uses the default shown above.
• Setting or importing an existing platform and key overwrites its value, preserves createdAt, and updates updatedAt.
• credentialsGet returns the plaintext value in data.value. A missing credential returns success: false. Listing returns masked values and timestamps sorted by platform and key; masked values can reveal a prefix.
• credentialsRotate requires an existing credential and stores refreshToken as its new value. It returns rotatedAt in its result but does not write that timestamp to the stored entry. It makes no external token refresh request.
• JSON import accepts an array or an object with platform, key, and value. Entries with missing or empty fields are skipped and reported as errors.
• CSV import reads platform, key, and value from each line, trims those values, ignores blank lines, and skips the first nonblank line if it contains "platform", ignoring case. Its line parser handles quoted commas and escaped double quotes.
• Import results report imported, skipped, and any errors. Parse errors and skipped entries can appear in a result with success: true.
• The exported CredentialVaultService also exposes deleteCredential and exportCredentials. Export returns plaintext values. The pack registers no delete or export tool.

License

Apache-2.0