@elizaos/plugin-secrets-manager 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,1461 @@
+import { IAgentRuntime, ServiceTypeName, Service, Plugin, World, UUID, Memory, Provider, Action } from '@elizaos/core';
+
+/**
+ * Plugin Secrets Manager - Shared Type Definitions
+ *
+ * This module defines all core types for the multi-level secrets management system.
+ * Designed for ElizaOS native storage: character settings, world metadata, and components.
+ */
+declare const SECRET_KEY_MAX_LENGTH = 256;
+declare const SECRET_VALUE_MAX_LENGTH = 65536;
+declare const SECRET_DESCRIPTION_MAX_LENGTH = 1024;
+declare const SECRET_KEY_PATTERN: RegExp;
+declare const MAX_ACCESS_LOG_ENTRIES = 1000;
+type SecretLevel = "global" | "world" | "user";
+type SecretType = "api_key" | "private_key" | "public_key" | "url" | "credential" | "token" | "config" | "secret";
+type SecretStatus = "missing" | "generating" | "validating" | "invalid" | "valid" | "expired" | "revoked";
+type SecretPermissionType = "read" | "write" | "delete" | "share";
+type ValidationStrategy = "none" | "api_key:openai" | "api_key:anthropic" | "api_key:groq" | "api_key:google" | "api_key:mistral" | "api_key:cohere" | "url:valid" | "url:reachable" | "custom";
+type StorageBackend = "memory" | "character" | "world" | "component";
+/**
+ * Configuration for a single secret/environment variable
+ */
+interface SecretConfig {
+    /** Type classification of the secret */
+    type: SecretType;
+    /** Whether this secret is required for the plugin to function */
+    required: boolean;
+    /** Human-readable description */
+    description: string;
+    /** Whether this secret can be auto-generated */
+    canGenerate: boolean;
+    /** Validation method to use */
+    validationMethod?: ValidationStrategy;
+    /** Current status of the secret */
+    status: SecretStatus;
+    /** Last error message if validation failed */
+    lastError?: string;
+    /** Number of validation attempts */
+    attempts: number;
+    /** Timestamp when secret was created */
+    createdAt?: number;
+    /** Timestamp when secret was last validated */
+    validatedAt?: number;
+    /** Plugin that declared this secret requirement */
+    plugin: string;
+    /** Storage level (global, world, or user) */
+    level: SecretLevel;
+    /** Owner entity ID for user-level secrets */
+    ownerId?: string;
+    /** World ID for world-level secrets */
+    worldId?: string;
+    /** Whether the value is encrypted */
+    encrypted?: boolean;
+    /** Explicit permissions granted to other entities */
+    permissions?: SecretPermission[];
+    /** List of entity IDs with shared access */
+    sharedWith?: string[];
+    /** Optional expiration timestamp */
+    expiresAt?: number;
+}
+/**
+ * Stored secret with value and config
+ */
+interface StoredSecret {
+    /** The secret value (may be encrypted) */
+    value: string | EncryptedSecret;
+    /** Secret configuration */
+    config: SecretConfig;
+}
+/**
+ * Context for secret operations - determines access level and scope
+ */
+interface SecretContext {
+    /** Storage level to operate on */
+    level: SecretLevel;
+    /** World ID (required for world-level operations) */
+    worldId?: string;
+    /** User ID (required for user-level operations) */
+    userId?: string;
+    /** Agent ID (always required) */
+    agentId: string;
+    /** Entity making the request (for permission checks) */
+    requesterId?: string;
+}
+/**
+ * Permission grant for a secret
+ */
+interface SecretPermission {
+    /** Entity ID that has this permission */
+    entityId: string;
+    /** List of allowed operations */
+    permissions: SecretPermissionType[];
+    /** Entity that granted this permission */
+    grantedBy: string;
+    /** Timestamp when permission was granted */
+    grantedAt: number;
+    /** Optional expiration timestamp */
+    expiresAt?: number;
+}
+/**
+ * Metadata collection for multiple secrets (without values)
+ */
+interface SecretMetadata {
+    [key: string]: SecretConfig;
+}
+/**
+ * Access log entry for auditing
+ */
+interface SecretAccessLog {
+    /** Secret key that was accessed */
+    secretKey: string;
+    /** Entity that performed the access */
+    accessedBy: string;
+    /** Type of access operation */
+    action: SecretPermissionType;
+    /** Timestamp of access */
+    timestamp: number;
+    /** Context of the access */
+    context: SecretContext;
+    /** Whether the access succeeded */
+    success: boolean;
+    /** Error message if access failed */
+    error?: string;
+}
+/**
+ * Encrypted secret container
+ */
+interface EncryptedSecret {
+    /** Encrypted value (base64) */
+    value: string;
+    /** Initialization vector (base64) */
+    iv: string;
+    /** Authentication tag for GCM mode (base64) */
+    authTag?: string;
+    /** Encryption algorithm used */
+    algorithm: "aes-256-gcm" | "aes-256-cbc";
+    /** Key identifier for key rotation */
+    keyId: string;
+}
+/**
+ * Key derivation parameters
+ */
+interface KeyDerivationParams {
+    /** Salt for key derivation (base64) */
+    salt: string;
+    /** Number of iterations for PBKDF2 */
+    iterations: number;
+    /** Algorithm used for derivation */
+    algorithm: "pbkdf2-sha256" | "argon2id";
+    /** Key length in bytes */
+    keyLength: number;
+}
+/**
+ * Secret requirement declared by a plugin
+ */
+interface PluginSecretRequirement {
+    /** Human-readable description */
+    description: string;
+    /** Type of secret */
+    type: SecretType;
+    /** Whether the secret is required for plugin to function */
+    required: boolean;
+    /** Validation method to use */
+    validationMethod?: ValidationStrategy;
+    /** Environment variable name (for backward compatibility) */
+    envVar?: string;
+    /** Whether this secret can be auto-generated */
+    canGenerate?: boolean;
+    /** Generation script if auto-generatable */
+    generationScript?: string;
+}
+/**
+ * Status of plugin requirements
+ */
+interface PluginRequirementStatus {
+    /** Plugin identifier */
+    pluginId: string;
+    /** Whether all required secrets are available */
+    ready: boolean;
+    /** List of missing required secrets */
+    missingRequired: string[];
+    /** List of missing optional secrets */
+    missingOptional: string[];
+    /** List of invalid secrets */
+    invalid: string[];
+    /** Overall status message */
+    message: string;
+}
+/**
+ * Callback for secret changes
+ */
+type SecretChangeCallback = (key: string, value: string | null, context: SecretContext) => Promise<void>;
+/**
+ * Plugin activation registration
+ */
+interface PendingPluginActivation {
+    /** Plugin identifier */
+    pluginId: string;
+    /** Required secrets for activation */
+    requiredSecrets: string[];
+    /** Callback to invoke when ready */
+    callback: () => Promise<void>;
+    /** Registration timestamp */
+    registeredAt: number;
+}
+/**
+ * Storage backend interface
+ */
+interface ISecretStorage {
+    /** Storage backend type */
+    readonly storageType: StorageBackend;
+    /** Initialize the storage backend */
+    initialize(): Promise<void>;
+    /** Check if a secret exists */
+    exists(key: string, context: SecretContext): Promise<boolean>;
+    /** Get a secret value */
+    get(key: string, context: SecretContext): Promise<string | null>;
+    /** Set a secret value */
+    set(key: string, value: string, context: SecretContext, config?: Partial<SecretConfig>): Promise<boolean>;
+    /** Delete a secret */
+    delete(key: string, context: SecretContext): Promise<boolean>;
+    /** List all secrets in a context */
+    list(context: SecretContext): Promise<SecretMetadata>;
+    /** Get secret configuration without value */
+    getConfig(key: string, context: SecretContext): Promise<SecretConfig | null>;
+    /** Update secret configuration */
+    updateConfig(key: string, context: SecretContext, config: Partial<SecretConfig>): Promise<boolean>;
+}
+/**
+ * Result of secret validation
+ */
+interface ValidationResult {
+    /** Whether the value is valid */
+    isValid: boolean;
+    /** Error message if invalid */
+    error?: string;
+    /** Additional details */
+    details?: string;
+    /** Validation timestamp */
+    validatedAt: number;
+}
+/**
+ * Custom validation function signature
+ */
+type CustomValidator = (key: string, value: string) => Promise<ValidationResult>;
+/**
+ * Validation strategy registry entry
+ */
+interface ValidationStrategyEntry {
+    /** Strategy identifier */
+    id: ValidationStrategy;
+    /** Human-readable name */
+    name: string;
+    /** Description of validation */
+    description: string;
+    /** Validator function */
+    validate: CustomValidator;
+}
+/**
+ * Script for auto-generating secrets
+ */
+interface GenerationScript {
+    /** Variable name to generate */
+    variableName: string;
+    /** Plugin that owns this script */
+    pluginName: string;
+    /** Script content (shell/node) */
+    script: string;
+    /** Required dependencies */
+    dependencies: string[];
+    /** Number of generation attempts */
+    attempts: number;
+    /** Last output */
+    output?: string;
+    /** Last error */
+    error?: string;
+    /** Current status */
+    status: "pending" | "running" | "success" | "failed";
+    /** Creation timestamp */
+    createdAt: number;
+}
+/**
+ * Secrets service configuration
+ */
+interface SecretsServiceConfig {
+    /** Whether to enable encryption */
+    enableEncryption: boolean;
+    /** Salt for key derivation */
+    encryptionSalt?: string;
+    /** Whether to enable access logging */
+    enableAccessLogging: boolean;
+    /** Maximum access log entries to keep */
+    maxAccessLogEntries: number;
+}
+/**
+ * Plugin activator service configuration
+ */
+interface PluginActivatorConfig {
+    /** Whether to enable auto-activation */
+    enableAutoActivation: boolean;
+    /** Polling interval for checking requirements (ms) */
+    pollingIntervalMs: number;
+    /** Maximum time to wait for secrets (ms, 0 = forever) */
+    maxWaitMs: number;
+}
+/**
+ * Secret change event
+ */
+interface SecretChangeEvent {
+    /** Event type */
+    type: "created" | "updated" | "deleted" | "expired";
+    /** Secret key */
+    key: string;
+    /** New value (null for deleted) */
+    value: string | null;
+    /** Previous value (if updated) */
+    previousValue?: string;
+    /** Context of the change */
+    context: SecretContext;
+    /** Timestamp */
+    timestamp: number;
+}
+/**
+ * Plugin activation event
+ */
+interface PluginActivationEvent {
+    /** Event type */
+    type: "queued" | "activated" | "failed" | "timeout";
+    /** Plugin identifier */
+    pluginId: string;
+    /** Missing secrets (if queued/failed) */
+    missingSecrets?: string[];
+    /** Error message (if failed) */
+    error?: string;
+    /** Timestamp */
+    timestamp: number;
+}
+type FormFieldType = "text" | "password" | "textarea" | "select" | "checkbox" | "radio" | "file" | "hidden";
+interface FormValidationRule {
+    /** Rule type */
+    type: "required" | "minLength" | "maxLength" | "pattern" | "custom";
+    /** Value for the rule */
+    value?: string | number | boolean;
+    /** Error message */
+    message: string;
+}
+interface FormField {
+    /** Field name (becomes secret key) */
+    name: string;
+    /** Field label */
+    label: string;
+    /** Field type */
+    type: FormFieldType;
+    /** Placeholder text */
+    placeholder?: string;
+    /** Default value */
+    defaultValue?: string;
+    /** Help text */
+    helpText?: string;
+    /** Options for select/radio */
+    options?: Array<{
+        value: string;
+        label: string;
+    }>;
+    /** Validation rules */
+    validation?: FormValidationRule[];
+    /** Whether field is disabled */
+    disabled?: boolean;
+    /** Custom CSS classes */
+    className?: string;
+}
+interface FormSchema {
+    /** Form title */
+    title: string;
+    /** Form description */
+    description?: string;
+    /** Form fields */
+    fields: FormField[];
+    /** Submit button text */
+    submitText?: string;
+    /** Cancel button text */
+    cancelText?: string;
+    /** Success message */
+    successMessage?: string;
+    /** Redirect URL after success */
+    redirectUrl?: string;
+}
+interface FormSession {
+    /** Session ID */
+    id: string;
+    /** Form schema */
+    schema: FormSchema;
+    /** Context for storing secrets */
+    context: SecretContext;
+    /** Expiration timestamp */
+    expiresAt: number;
+    /** Created timestamp */
+    createdAt: number;
+    /** Public URL for form access */
+    publicUrl?: string;
+    /** Tunnel ID (if using ngrok) */
+    tunnelId?: string;
+    /** Whether form has been submitted */
+    submitted: boolean;
+    /** Submission timestamp */
+    submittedAt?: number;
+}
+interface FormSubmission {
+    /** Session ID */
+    sessionId: string;
+    /** Submitted values */
+    values: Record<string, string>;
+    /** Submission timestamp */
+    submittedAt: number;
+    /** Client IP address */
+    clientIp?: string;
+    /** User agent */
+    userAgent?: string;
+}
+declare class SecretsError extends Error {
+    readonly code: string;
+    readonly details?: Record<string, unknown> | undefined;
+    constructor(message: string, code: string, details?: Record<string, unknown> | undefined);
+}
+declare class PermissionDeniedError extends SecretsError {
+    constructor(key: string, action: SecretPermissionType, context: SecretContext);
+}
+declare class SecretNotFoundError extends SecretsError {
+    constructor(key: string, context: SecretContext);
+}
+declare class ValidationError extends SecretsError {
+    constructor(key: string, message: string, details?: Record<string, unknown>);
+}
+declare class EncryptionError extends SecretsError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+declare class StorageError extends SecretsError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+
+/**
+ * Encryption module for secrets management
+ *
+ * Provides AES-256-GCM encryption with secure key derivation for protecting sensitive data.
+ * Compatible with the OpenClaw encryption approach while providing additional security features.
+ */
+
+/**
+ * Generate a cryptographically secure random salt
+ */
+declare function generateSalt(length?: number): string;
+/**
+ * Generate a random encryption key
+ */
+declare function generateKey(): Buffer;
+/**
+ * Derive an encryption key from a password/passphrase using PBKDF2
+ *
+ * @param password - The password or passphrase to derive from
+ * @param salt - The salt (should be unique per key)
+ * @param iterations - Number of PBKDF2 iterations (default: 100000)
+ * @returns The derived key as a Buffer
+ */
+declare function deriveKeyPbkdf2(password: string, salt: string | Buffer, iterations?: number): Buffer;
+/**
+ * Derive a key from agent ID and salt (OpenClaw compatible)
+ *
+ * This method provides backward compatibility with OpenClaw's key derivation approach.
+ * For new implementations, prefer deriveKeyPbkdf2 or deriveKeyScrypt.
+ *
+ * @param agentId - The agent's unique identifier
+ * @param salt - Optional salt (defaults to 'default-salt')
+ * @returns The derived key as a Buffer
+ */
+declare function deriveKeyFromAgentId(agentId: string, salt?: string): Buffer;
+/**
+ * Encrypt a value using the default algorithm (GCM)
+ */
+declare function encrypt(plaintext: string, key: Buffer, keyId?: string): EncryptedSecret;
+/**
+ * Decrypt a value using the appropriate algorithm
+ *
+ * @param encrypted - The encrypted secret container (or raw string for backward compat)
+ * @param key - The decryption key (32 bytes)
+ * @returns The decrypted plaintext
+ */
+declare function decrypt(encrypted: EncryptedSecret | string, key: Buffer): string;
+/**
+ * Check if a value appears to be an encrypted secret
+ */
+declare function isEncryptedSecret(value: unknown): value is EncryptedSecret;
+/**
+ * Generate a secure random string for tokens, IDs, etc.
+ */
+declare function generateSecureToken(length?: number): string;
+/**
+ * Manages encryption keys with support for rotation and multiple key IDs
+ */
+declare class KeyManager {
+    private keys;
+    private currentKeyId;
+    private derivationParams;
+    constructor(options?: {
+        primaryKey?: Buffer;
+        primaryKeyId?: string;
+        derivationParams?: KeyDerivationParams;
+    });
+    /**
+     * Initialize with a password-derived key
+     */
+    initializeFromPassword(password: string, salt?: string): void;
+    /**
+     * Initialize with an agent ID (OpenClaw compatible)
+     */
+    initializeFromAgentId(agentId: string, salt?: string): void;
+    /**
+     * Add a key for decryption (supports key rotation)
+     */
+    addKey(keyId: string, key: Buffer): void;
+    /**
+     * Set the current key for encryption
+     */
+    setCurrentKey(keyId: string): void;
+    /**
+     * Get the current key ID
+     */
+    getCurrentKeyId(): string;
+    /**
+     * Get a key by ID
+     */
+    getKey(keyId: string): Buffer | undefined;
+    /**
+     * Get the current encryption key
+     */
+    getCurrentKey(): Buffer;
+    /**
+     * Get derivation parameters (for storage)
+     */
+    getDerivationParams(): KeyDerivationParams | null;
+    /**
+     * Encrypt a value with the current key
+     */
+    encrypt(plaintext: string): EncryptedSecret;
+    /**
+     * Decrypt a value (automatically selects the correct key)
+     */
+    decrypt(encrypted: EncryptedSecret | string): string;
+    /**
+     * Re-encrypt a value with the current key (for key rotation)
+     */
+    reencrypt(encrypted: EncryptedSecret): EncryptedSecret;
+    /**
+     * Clear all keys from memory
+     */
+    clear(): void;
+}
+
+/**
+ * Storage Interface Definitions
+ *
+ * Defines the contract that all storage backends must implement.
+ * Designed for ElizaOS native storage patterns.
+ */
+
+/**
+ * Abstract base class for secret storage implementations
+ *
+ * Provides common functionality and enforces the storage interface.
+ */
+declare abstract class BaseSecretStorage implements ISecretStorage {
+    abstract readonly storageType: StorageBackend;
+    abstract initialize(): Promise<void>;
+    abstract exists(key: string, context: SecretContext): Promise<boolean>;
+    abstract get(key: string, context: SecretContext): Promise<string | null>;
+    abstract set(key: string, value: string, context: SecretContext, config?: Partial<SecretConfig>): Promise<boolean>;
+    abstract delete(key: string, context: SecretContext): Promise<boolean>;
+    abstract list(context: SecretContext): Promise<SecretMetadata>;
+    abstract getConfig(key: string, context: SecretContext): Promise<SecretConfig | null>;
+    abstract updateConfig(key: string, context: SecretContext, config: Partial<SecretConfig>): Promise<boolean>;
+    /**
+     * Create a default secret configuration
+     */
+    protected createDefaultConfig(key: string, context: SecretContext, partial?: Partial<SecretConfig>): SecretConfig;
+}
+/**
+ * Composite storage that delegates to multiple backends based on context
+ */
+declare class CompositeSecretStorage implements ISecretStorage {
+    readonly storageType: StorageBackend;
+    private globalStorage;
+    private worldStorage;
+    private userStorage;
+    constructor(options: {
+        globalStorage: ISecretStorage;
+        worldStorage: ISecretStorage;
+        userStorage: ISecretStorage;
+    });
+    initialize(): Promise<void>;
+    private getStorageForContext;
+    exists(key: string, context: SecretContext): Promise<boolean>;
+    get(key: string, context: SecretContext): Promise<string | null>;
+    set(key: string, value: string, context: SecretContext, config?: Partial<SecretConfig>): Promise<boolean>;
+    delete(key: string, context: SecretContext): Promise<boolean>;
+    list(context: SecretContext): Promise<SecretMetadata>;
+    getConfig(key: string, context: SecretContext): Promise<SecretConfig | null>;
+    updateConfig(key: string, context: SecretContext, config: Partial<SecretConfig>): Promise<boolean>;
+}
+
+/**
+ * Memory-based Secret Storage
+ *
+ * In-memory storage backend for secrets. Useful for testing and
+ * ephemeral environments where persistence is not required.
+ */
+
+/**
+ * Memory-based secret storage implementation
+ */
+declare class MemorySecretStorage extends BaseSecretStorage {
+    readonly storageType: StorageBackend;
+    private store;
+    initialize(): Promise<void>;
+    exists(key: string, context: SecretContext): Promise<boolean>;
+    get(key: string, context: SecretContext): Promise<string | null>;
+    set(key: string, value: string, context: SecretContext, config?: Partial<SecretConfig>): Promise<boolean>;
+    delete(key: string, context: SecretContext): Promise<boolean>;
+    list(context: SecretContext): Promise<SecretMetadata>;
+    getConfig(key: string, context: SecretContext): Promise<SecretConfig | null>;
+    updateConfig(key: string, context: SecretContext, config: Partial<SecretConfig>): Promise<boolean>;
+    /**
+     * Generate a storage key from the secret key and context
+     */
+    private generateStorageKey;
+    /**
+     * Get the storage key prefix for a context level
+     */
+    private getContextPrefix;
+    /**
+     * Extract the original key from a storage key
+     */
+    private extractOriginalKey;
+    /**
+     * Clear all stored secrets (for testing)
+     */
+    clear(): void;
+    /**
+     * Get the number of stored secrets (for testing)
+     */
+    size(): number;
+}
+
+/**
+ * Character Settings Storage
+ *
+ * Stores global secrets in the character's settings.secrets object.
+ * This is the primary storage for agent-level configuration and API keys.
+ *
+ * Note: This implementation directly accesses character.settings rather than
+ * using getSetting()/setSetting() because those methods don't support object
+ * values - they only return primitives (string | boolean | number | null).
+ */
+
+/**
+ * Character settings-based storage for global secrets
+ *
+ * Secrets are stored in character.settings.secrets with metadata
+ * tracked separately for configuration management.
+ */
+declare class CharacterSettingsStorage extends BaseSecretStorage {
+    readonly storageType: StorageBackend;
+    private runtime;
+    private keyManager;
+    private initialized;
+    constructor(runtime: IAgentRuntime, keyManager: KeyManager);
+    initialize(): Promise<void>;
+    /**
+     * Ensure the character.settings.secrets structure exists
+     */
+    private ensureSettingsStructure;
+    exists(key: string, _context: SecretContext): Promise<boolean>;
+    get(key: string, context: SecretContext): Promise<string | null>;
+    set(key: string, value: string, context: SecretContext, config?: Partial<SecretConfig>): Promise<boolean>;
+    delete(key: string, _context: SecretContext): Promise<boolean>;
+    list(_context: SecretContext): Promise<SecretMetadata>;
+    getConfig(key: string, context: SecretContext): Promise<SecretConfig | null>;
+    updateConfig(key: string, _context: SecretContext, config: Partial<SecretConfig>): Promise<boolean>;
+    /**
+     * Get the secrets object from character settings
+     *
+     * Accesses character.settings.secrets directly instead of using getSetting()
+     * because getSetting() only returns primitives, not objects.
+     */
+    private getSecretsObject;
+    /**
+     * Migrate legacy environment variable format to new format
+     */
+    migrateFromEnvVars(envVarPrefix?: string): Promise<number>;
+    /**
+     * Get a secret as an environment variable (for backward compatibility)
+     */
+    getAsEnvVar(key: string): Promise<string | null>;
+    /**
+     * Sync a secret to process.env (for plugins that read env vars directly)
+     */
+    syncToEnv(key: string, envVarName?: string): Promise<boolean>;
+    /**
+     * Sync all secrets to process.env
+     */
+    syncAllToEnv(): Promise<number>;
+}
+
+/**
+ * World Metadata Storage
+ *
+ * Stores world-level secrets in the world's metadata.secrets object.
+ * This is used for server/channel-specific configuration like Discord tokens.
+ */
+
+/**
+ * World metadata-based storage for world-level secrets
+ *
+ * Secrets are stored in world.metadata.secrets with access control
+ * based on world roles (OWNER/ADMIN can write, all members can read).
+ */
+declare class WorldMetadataStorage extends BaseSecretStorage {
+    readonly storageType: StorageBackend;
+    private runtime;
+    private keyManager;
+    private worldCache;
+    constructor(runtime: IAgentRuntime, keyManager: KeyManager);
+    initialize(): Promise<void>;
+    exists(key: string, context: SecretContext): Promise<boolean>;
+    get(key: string, context: SecretContext): Promise<string | null>;
+    set(key: string, value: string, context: SecretContext, config?: Partial<SecretConfig>): Promise<boolean>;
+    delete(key: string, context: SecretContext): Promise<boolean>;
+    list(context: SecretContext): Promise<SecretMetadata>;
+    getConfig(key: string, context: SecretContext): Promise<SecretConfig | null>;
+    updateConfig(key: string, context: SecretContext, config: Partial<SecretConfig>): Promise<boolean>;
+    /**
+     * Get a world from cache or database
+     */
+    private getWorld;
+    /**
+     * Get secrets object from world metadata
+     */
+    private getWorldSecrets;
+    /**
+     * Check if a user has write permission in a world
+     */
+    private checkWritePermission;
+    /**
+     * Clear the world cache
+     */
+    clearCache(): void;
+    /**
+     * Invalidate a specific world in the cache
+     */
+    invalidateWorld(worldId: string): void;
+}
+
+/**
+ * Component Storage
+ *
+ * Stores user-level secrets as Components in the ElizaOS database.
+ * Each user's secrets are isolated via the component's entityId.
+ */
+
+/**
+ * Component-based storage for user-level secrets
+ *
+ * Each secret is stored as a Component with type='secret' and entityId
+ * set to the user's ID, providing natural isolation per user.
+ */
+declare class ComponentSecretStorage extends BaseSecretStorage {
+    readonly storageType: StorageBackend;
+    private runtime;
+    private keyManager;
+    constructor(runtime: IAgentRuntime, keyManager: KeyManager);
+    initialize(): Promise<void>;
+    exists(key: string, context: SecretContext): Promise<boolean>;
+    get(key: string, context: SecretContext): Promise<string | null>;
+    set(key: string, value: string, context: SecretContext, config?: Partial<SecretConfig>): Promise<boolean>;
+    delete(key: string, context: SecretContext): Promise<boolean>;
+    list(context: SecretContext): Promise<SecretMetadata>;
+    getConfig(key: string, context: SecretContext): Promise<SecretConfig | null>;
+    updateConfig(key: string, context: SecretContext, config: Partial<SecretConfig>): Promise<boolean>;
+    /**
+     * Find a secret component for a user by key
+     */
+    private findSecretComponent;
+    /**
+     * Get all secret keys for a user
+     */
+    listKeys(userId: string): Promise<string[]>;
+    /**
+     * Delete all secrets for a user
+     */
+    deleteAllForUser(userId: string): Promise<number>;
+    /**
+     * Count secrets for a user
+     */
+    countForUser(userId: string): Promise<number>;
+}
+
+/**
+ * Secrets Service
+ *
+ * Core service for multi-level secret management in ElizaOS.
+ * Provides unified API for accessing global, world, and user secrets
+ * with encryption, access control, and change notification support.
+ */
+
+/**
+ * Service type identifier
+ */
+declare const SECRETS_SERVICE_TYPE: ServiceTypeName;
+/**
+ * Secrets Service
+ *
+ * Unified service for managing secrets at all levels:
+ * - Global: Stored in character settings (agent-wide config, API keys)
+ * - World: Stored in world metadata (server/channel-specific)
+ * - User: Stored as components (per-user secrets)
+ */
+declare class SecretsService extends Service {
+    static serviceType: ServiceTypeName;
+    capabilityDescription: string;
+    private secretsConfig;
+    private keyManager;
+    private storage;
+    private globalStorage;
+    private worldStorage;
+    private userStorage;
+    private accessLogs;
+    private changeCallbacks;
+    private globalChangeCallbacks;
+    constructor(runtime?: IAgentRuntime, config?: Partial<SecretsServiceConfig>);
+    /**
+     * Start the service
+     */
+    static start(runtime: IAgentRuntime, config?: Partial<SecretsServiceConfig>): Promise<SecretsService>;
+    /**
+     * Initialize the service
+     */
+    private initialize;
+    /**
+     * Stop the service
+     */
+    stop(): Promise<void>;
+    /**
+     * Get a secret value
+     */
+    get(key: string, context: SecretContext): Promise<string | null>;
+    /**
+     * Set a secret value
+     */
+    set(key: string, value: string, context: SecretContext, config?: Partial<SecretConfig>): Promise<boolean>;
+    /**
+     * Delete a secret
+     */
+    delete(key: string, context: SecretContext): Promise<boolean>;
+    /**
+     * Check if a secret exists
+     */
+    exists(key: string, context: SecretContext): Promise<boolean>;
+    /**
+     * List secrets (metadata only, no values)
+     */
+    list(context: SecretContext): Promise<SecretMetadata>;
+    /**
+     * Get secret configuration
+     */
+    getConfig(key: string, context: SecretContext): Promise<SecretConfig | null>;
+    /**
+     * Update secret configuration
+     */
+    updateConfig(key: string, context: SecretContext, config: Partial<SecretConfig>): Promise<boolean>;
+    /**
+     * Get a global secret (agent-level)
+     */
+    getGlobal(key: string): Promise<string | null>;
+    /**
+     * Set a global secret (agent-level)
+     */
+    setGlobal(key: string, value: string, config?: Partial<SecretConfig>): Promise<boolean>;
+    /**
+     * Get a world secret
+     */
+    getWorld(key: string, worldId: string): Promise<string | null>;
+    /**
+     * Set a world secret
+     */
+    setWorld(key: string, value: string, worldId: string, config?: Partial<SecretConfig>): Promise<boolean>;
+    /**
+     * Get a user secret
+     */
+    getUser(key: string, userId: string): Promise<string | null>;
+    /**
+     * Set a user secret
+     */
+    setUser(key: string, value: string, userId: string, config?: Partial<SecretConfig>): Promise<boolean>;
+    /**
+     * Validate a secret value
+     */
+    validate(key: string, value: string, strategy?: string): Promise<ValidationResult>;
+    /**
+     * Get available validation strategies
+     */
+    getValidationStrategies(): string[];
+    /**
+     * Check which secrets are missing for a plugin
+     */
+    checkPluginRequirements(pluginId: string, requirements: Record<string, PluginSecretRequirement>): Promise<{
+        ready: boolean;
+        missingRequired: string[];
+        missingOptional: string[];
+        invalid: string[];
+    }>;
+    /**
+     * Get missing secrets for a set of keys
+     */
+    getMissingSecrets(keys: string[], level?: "global" | "world" | "user"): Promise<string[]>;
+    /**
+     * Register a callback for changes to a specific secret
+     */
+    onSecretChanged(key: string, callback: SecretChangeCallback): () => void;
+    /**
+     * Register a callback for all secret changes
+     */
+    onAnySecretChanged(callback: SecretChangeCallback): () => void;
+    /**
+     * Emit a change event to registered callbacks
+     */
+    private emitChangeEvent;
+    /**
+     * Log a secret access attempt
+     */
+    private logAccess;
+    /**
+     * Get access logs
+     */
+    getAccessLogs(filter?: {
+        key?: string;
+        action?: string;
+        context?: Partial<SecretContext>;
+        since?: number;
+    }): SecretAccessLog[];
+    /**
+     * Clear access logs
+     */
+    clearAccessLogs(): void;
+    /**
+     * Get the global storage backend
+     */
+    getGlobalStorage(): CharacterSettingsStorage;
+    /**
+     * Get the world storage backend
+     */
+    getWorldStorage(): WorldMetadataStorage;
+    /**
+     * Get the user storage backend
+     */
+    getUserStorage(): ComponentSecretStorage;
+    /**
+     * Get the key manager (for advanced use cases)
+     */
+    getKeyManager(): KeyManager;
+}
+
+/**
+ * Plugin Activator Service
+ *
+ * Enables dynamic plugin activation when required secrets become available.
+ * Plugins can register for activation with their secret requirements,
+ * and will be activated automatically once all secrets are present.
+ */
+
+/**
+ * Service type identifier
+ */
+declare const PLUGIN_ACTIVATOR_SERVICE_TYPE: ServiceTypeName;
+/**
+ * Extended Plugin interface with secret requirements
+ */
+interface PluginWithSecrets extends Plugin {
+    /** Required secrets for this plugin to function */
+    requiredSecrets?: Record<string, PluginSecretRequirement>;
+    /** Called when all required secrets become available */
+    onSecretsReady?: (runtime: IAgentRuntime) => Promise<void>;
+    /** Called when a required secret changes */
+    onSecretChanged?: (key: string, value: string | null, runtime: IAgentRuntime) => Promise<void>;
+}
+/**
+ * Plugin Activator Service
+ *
+ * Manages the lifecycle of plugins that depend on secrets:
+ * - Tracks plugins waiting for secrets
+ * - Automatically activates plugins when requirements are met
+ * - Notifies plugins when their secrets change
+ */
+declare class PluginActivatorService extends Service {
+    static serviceType: ServiceTypeName;
+    capabilityDescription: string;
+    private activatorConfig;
+    private secretsService;
+    private pendingPlugins;
+    private activatedPlugins;
+    private pluginSecretMapping;
+    private pollingInterval;
+    private unsubscribeSecretChanges;
+    constructor(runtime?: IAgentRuntime, config?: Partial<PluginActivatorConfig>);
+    /**
+     * Start the service
+     */
+    static start(runtime: IAgentRuntime, config?: Partial<PluginActivatorConfig>): Promise<PluginActivatorService>;
+    /**
+     * Initialize the service
+     */
+    private initialize;
+    /**
+     * Stop the service
+     */
+    stop(): Promise<void>;
+    /**
+     * Register a plugin for activation when secrets are ready
+     */
+    registerPlugin(plugin: PluginWithSecrets, activationCallback?: () => Promise<void>): Promise<boolean>;
+    /**
+     * Unregister a pending plugin
+     */
+    unregisterPlugin(pluginId: string): boolean;
+    /**
+     * Activate a plugin
+     */
+    private activatePlugin;
+    /**
+     * Check requirements for a plugin
+     */
+    checkPluginRequirements(plugin: PluginWithSecrets): Promise<PluginRequirementStatus>;
+    /**
+     * Get status of all registered plugins
+     */
+    getPluginStatuses(): Map<string, {
+        pending: boolean;
+        activated: boolean;
+        missingSecrets: string[];
+    }>;
+    /**
+     * Handle secret change event
+     */
+    private onSecretChanged;
+    /**
+     * Get missing secrets from a list
+     */
+    private getMissingSecrets;
+    /**
+     * Start polling for pending plugins
+     */
+    private startPolling;
+    /**
+     * Stop polling
+     */
+    private stopPolling;
+    /**
+     * Check all pending plugins
+     */
+    private checkPendingPlugins;
+    /**
+     * Get list of pending plugins
+     */
+    getPendingPlugins(): string[];
+    /**
+     * Get list of activated plugins
+     */
+    getActivatedPlugins(): string[];
+    /**
+     * Check if a plugin is pending
+     */
+    isPending(pluginId: string): boolean;
+    /**
+     * Check if a plugin is activated
+     */
+    isActivated(pluginId: string): boolean;
+    /**
+     * Get secrets required by pending plugins
+     */
+    getRequiredSecrets(): Set<string>;
+    /**
+     * Get plugins waiting for a specific secret
+     */
+    getPluginsWaitingFor(secretKey: string): string[];
+}
+
+/**
+ * Onboarding configuration types and utilities.
+ *
+ * Provides the structure for defining secret requirements per agent/plugin,
+ * supporting both conversational and form-based collection flows.
+ */
+
+/**
+ * Setting definition for onboarding.
+ * Compatible with the-org OnboardingConfig format.
+ */
+interface OnboardingSetting {
+    /** Display name */
+    name: string;
+    /** Description for LLM context */
+    description: string;
+    /** Prompt shown when asking user for this setting */
+    usageDescription?: string;
+    /** Whether this is a secret (should be encrypted) */
+    secret: boolean;
+    /** Whether this should be visible in non-onboarding contexts */
+    public: boolean;
+    /** Whether this setting is required */
+    required: boolean;
+    /** Settings that must be configured first */
+    dependsOn: string[];
+    /** Validation function */
+    validation?: (value: string) => boolean;
+    /** Validation method name (openai, anthropic, url, etc.) */
+    validationMethod?: string;
+    /** Secret type */
+    type?: SecretType;
+    /** Environment variable to sync to */
+    envVar?: string;
+    /** Default value if not set */
+    defaultValue?: string;
+    /** Current value (set during onboarding) */
+    value?: string | null;
+    /** Conditional visibility based on other settings */
+    visibleIf?: (settings: Record<string, OnboardingSetting>) => boolean;
+    /** Callback when value is set */
+    onSetAction?: (value: string | boolean) => string | void;
+}
+/**
+ * Onboarding configuration for an agent or plugin.
+ */
+interface OnboardingConfig {
+    /** Setting definitions */
+    settings: Record<string, OnboardingSetting>;
+    /** Optional platform-specific messages */
+    messages?: {
+        welcome?: string[];
+        askSetting?: string;
+        settingUpdated?: string;
+        allComplete?: string;
+        error?: string;
+    };
+    /** Onboarding flow mode */
+    mode?: "conversational" | "form" | "hybrid";
+}
+/**
+ * Default onboarding messages.
+ */
+declare const DEFAULT_ONBOARDING_MESSAGES: {
+    welcome: string[];
+    askSetting: string;
+    settingUpdated: string;
+    allComplete: string;
+    error: string;
+};
+/**
+ * Common API key settings for quick setup.
+ */
+declare const COMMON_API_KEY_SETTINGS: Record<string, Partial<OnboardingSetting>>;
+/**
+ * Create an onboarding config from a list of required secret keys.
+ */
+declare function createOnboardingConfig(requiredKeys: string[], optionalKeys?: string[], customSettings?: Record<string, Partial<OnboardingSetting>>): OnboardingConfig;
+/**
+ * Get unconfigured required settings from an onboarding config.
+ */
+declare function getUnconfiguredRequired(config: OnboardingConfig): Array<[string, OnboardingSetting]>;
+/**
+ * Get unconfigured optional settings from an onboarding config.
+ */
+declare function getUnconfiguredOptional(config: OnboardingConfig): Array<[string, OnboardingSetting]>;
+/**
+ * Check if all required settings are configured.
+ */
+declare function isOnboardingComplete(config: OnboardingConfig): boolean;
+/**
+ * Get the next setting to configure (respects dependencies).
+ */
+declare function getNextSetting(config: OnboardingConfig): [string, OnboardingSetting] | null;
+/**
+ * Generate a prompt for the LLM to ask for a specific setting.
+ */
+declare function generateSettingPrompt(key: string, setting: OnboardingSetting, agentName: string): string;
+
+/**
+ * Onboarding Service
+ *
+ * Manages the secrets onboarding flow across platforms (Discord, Telegram, etc.)
+ * Supports both conversational and form-based collection modes.
+ */
+
+declare const ONBOARDING_SERVICE_TYPE: ServiceTypeName;
+/**
+ * Onboarding session state.
+ */
+interface OnboardingSession {
+    worldId: UUID;
+    userId: UUID;
+    roomId: UUID;
+    config: OnboardingConfig;
+    currentSettingKey: string | null;
+    startedAt: number;
+    lastActivityAt: number;
+    platform: "discord" | "telegram" | "other";
+    mode: "conversational" | "form" | "hybrid";
+}
+/**
+ * Onboarding Service for secrets collection.
+ */
+declare class OnboardingService extends Service {
+    static serviceType: ServiceTypeName;
+    capabilityDescription: string;
+    private secretsService;
+    private sessions;
+    constructor(runtime?: IAgentRuntime);
+    /**
+     * Start the service
+     */
+    static start(runtime: IAgentRuntime): Promise<OnboardingService>;
+    /**
+     * Initialize the service
+     */
+    private initialize;
+    stop(): Promise<void>;
+    /**
+     * Register platform-specific event handlers.
+     */
+    private registerEvents;
+    /**
+     * Initialize onboarding for a world with the given config.
+     */
+    initializeOnboarding(world: World, config: OnboardingConfig): Promise<void>;
+    /**
+     * Start onboarding via DM (Discord).
+     */
+    startDiscordOnboardingDM(serverId: string, ownerId: string, worldId: UUID, config: OnboardingConfig): Promise<void>;
+    /**
+     * Start onboarding via deep link (Telegram).
+     */
+    startTelegramOnboarding(world: World, chat: {
+        id: string | number;
+    }, entities: Array<{
+        metadata?: {
+            telegram?: {
+                id: string;
+                username: string;
+                adminTitle?: string;
+            };
+        };
+    }>, botUsername: string): Promise<void>;
+    /**
+     * Start a new onboarding session.
+     */
+    startSession(worldId: UUID, userId: UUID, roomId: UUID, config: OnboardingConfig, platform?: "discord" | "telegram" | "other", mode?: "conversational" | "form" | "hybrid"): Promise<OnboardingSession>;
+    /**
+     * Get an active session by room ID.
+     */
+    getSession(roomId: UUID): OnboardingSession | null;
+    /**
+     * Process a user message during onboarding.
+     */
+    processMessage(roomId: UUID, message: Memory): Promise<{
+        shouldRespond: boolean;
+        response?: string;
+        updatedKey?: string;
+        complete?: boolean;
+    }>;
+    /**
+     * End an onboarding session.
+     */
+    endSession(roomId: UUID): void;
+    /**
+     * Get the onboarding status for a world.
+     */
+    getOnboardingStatus(worldId: UUID): Promise<{
+        initialized: boolean;
+        complete: boolean;
+        configuredCount: number;
+        requiredCount: number;
+        missingRequired: string[];
+    }>;
+    /**
+     * Generate the SETTINGS provider context for LLM.
+     */
+    generateSettingsContext(config: OnboardingConfig, isOnboarding: boolean, agentName: string): string;
+}
+
+/**
+ * Onboarding Provider
+ *
+ * Provides onboarding status and context to the LLM during secret collection.
+ * Injects prompts about required settings into the agent's context.
+ */
+
+/**
+ * Onboarding settings provider - injects onboarding context into LLM prompts.
+ */
+declare const onboardingSettingsProvider: Provider;
+/**
+ * Provider that shows what secrets are still needed.
+ */
+declare const missingSecretsProvider: Provider;
+
+/**
+ * Update Settings Action
+ *
+ * Extracts and saves setting values from natural language user messages.
+ * Uses LLM to parse user responses and map them to settings.
+ */
+
+/**
+ * UPDATE_SETTINGS Action - extracts and saves settings from natural language.
+ */
+declare const updateSettingsAction: Action;
+
+/**
+ * Secret Validation Module
+ *
+ * Provides validation strategies for different types of secrets
+ * including API keys, URLs, and custom validation.
+ */
+
+/**
+ * Validation strategy implementations
+ */
+declare const ValidationStrategies: Record<string, CustomValidator>;
+/**
+ * Register a custom validator
+ */
+declare function registerValidator(name: string, validator: CustomValidator): void;
+/**
+ * Unregister a custom validator
+ */
+declare function unregisterValidator(name: string): boolean;
+/**
+ * Validate a secret value
+ */
+declare function validateSecret(key: string, value: string, strategy?: string): Promise<ValidationResult>;
+/**
+ * Infer validation strategy from secret key name
+ */
+declare function inferValidationStrategy(key: string): ValidationStrategy;
+
+/**
+ * Secrets Manager Plugin
+ *
+ * Comprehensive secret management for ElizaOS with:
+ * - Multi-level storage (global, world, user)
+ * - Encryption at rest
+ * - Dynamic plugin activation when secrets become available
+ * - Natural language secret management
+ * - Conversational onboarding flow (Discord, Telegram)
+ */
+
+/**
+ * Plugin configuration
+ */
+interface SecretsManagerPluginConfig {
+    /** Enable encryption for stored secrets (default: true) */
+    enableEncryption?: boolean;
+    /** Custom salt for encryption key derivation */
+    encryptionSalt?: string;
+    /** Enable access logging (default: true) */
+    enableAccessLogging?: boolean;
+    /** Enable automatic plugin activation when secrets are available (default: true) */
+    enableAutoActivation?: boolean;
+    /** Polling interval for checking plugin requirements (ms, default: 5000) */
+    activationPollingMs?: number;
+}
+/**
+ * Secrets Manager Plugin
+ *
+ * Provides comprehensive secret management capabilities:
+ *
+ * **Storage Levels:**
+ * - Global: Agent-wide secrets (API keys, tokens) stored in character settings
+ * - World: Server/channel-specific secrets stored in world metadata
+ * - User: Per-user secrets stored as components
+ *
+ * **Features:**
+ * - Automatic encryption using AES-256-GCM
+ * - Natural language secret management via actions
+ * - Plugin activation when required secrets become available
+ * - Access logging and auditing
+ * - Backward compatibility with ENV_ prefixed settings
+ *
+ * **Usage:**
+ * ```typescript
+ * import { secretsManagerPlugin } from '@elizaos/plugin-secrets-manager';
+ *
+ * const runtime = createAgentRuntime({
+ *   plugins: [secretsManagerPlugin],
+ * });
+ *
+ * // Get the secrets service
+ * const secrets = runtime.getService<SecretsService>('SECRETS');
+ *
+ * // Set a global secret
+ * await secrets.setGlobal('OPENAI_API_KEY', 'sk-...');
+ *
+ * // Get a global secret
+ * const apiKey = await secrets.getGlobal('OPENAI_API_KEY');
+ * ```
+ */
+declare const secretsManagerPlugin: Plugin;
+
+/**
+ * Set Secret Action
+ *
+ * Allows the agent to set secrets from user input through natural language.
+ * Extracts key-value pairs and stores them at the appropriate level.
+ */
+
+/**
+ * Set Secret Action
+ */
+declare const setSecretAction: Action;
+
+/**
+ * Manage Secret Action
+ *
+ * Comprehensive action for managing secrets through natural language.
+ * Supports get, set, delete, and list operations at different levels.
+ */
+
+/**
+ * Manage Secret Action
+ */
+declare const manageSecretAction: Action;
+
+/**
+ * Secrets Status Provider
+ *
+ * Provides context about the agent's secret configuration status
+ * to help the LLM understand what capabilities are available.
+ */
+
+/**
+ * Secrets Status Provider
+ *
+ * Adds information about configured secrets to the agent's context,
+ * without exposing actual secret values.
+ */
+declare const secretsStatusProvider: Provider;
+/**
+ * Secrets Info Provider
+ *
+ * Provides detailed information about specific secrets when relevant
+ * to the current conversation context.
+ */
+declare const secretsInfoProvider: Provider;
+
+export { BaseSecretStorage, COMMON_API_KEY_SETTINGS, CharacterSettingsStorage, ComponentSecretStorage, CompositeSecretStorage, type CustomValidator, DEFAULT_ONBOARDING_MESSAGES, type EncryptedSecret, EncryptionError, type FormField, type FormFieldType, type FormSchema, type FormSession, type FormSubmission, type FormValidationRule, type GenerationScript, type ISecretStorage, type KeyDerivationParams, KeyManager, MAX_ACCESS_LOG_ENTRIES, MemorySecretStorage, ONBOARDING_SERVICE_TYPE, type OnboardingConfig, OnboardingService, type OnboardingSetting, PLUGIN_ACTIVATOR_SERVICE_TYPE, type PendingPluginActivation, PermissionDeniedError, type PluginActivationEvent, type PluginActivatorConfig, PluginActivatorService, type PluginRequirementStatus, type PluginSecretRequirement, type PluginWithSecrets, SECRETS_SERVICE_TYPE, SECRET_DESCRIPTION_MAX_LENGTH, SECRET_KEY_MAX_LENGTH, SECRET_KEY_PATTERN, SECRET_VALUE_MAX_LENGTH, type SecretAccessLog, type SecretChangeCallback, type SecretChangeEvent, type SecretConfig, type SecretContext, type SecretLevel, type SecretMetadata, SecretNotFoundError, type SecretPermission, type SecretPermissionType, type SecretStatus, type SecretType, SecretsError, type SecretsManagerPluginConfig, SecretsService, type SecretsServiceConfig, type StorageBackend, StorageError, type StoredSecret, ValidationError, type ValidationResult, ValidationStrategies, type ValidationStrategy, type ValidationStrategyEntry, WorldMetadataStorage, createOnboardingConfig, decrypt, secretsManagerPlugin as default, deriveKeyFromAgentId, deriveKeyPbkdf2, encrypt, generateKey, generateSalt, generateSecureToken, generateSettingPrompt, getNextSetting, getUnconfiguredOptional, getUnconfiguredRequired, inferValidationStrategy, isEncryptedSecret, isOnboardingComplete, manageSecretAction, missingSecretsProvider, onboardingSettingsProvider, registerValidator, secretsInfoProvider, secretsManagerPlugin, secretsStatusProvider, setSecretAction, unregisterValidator, updateSettingsAction, validateSecret };