@elizaos/ui 2.0.0-alpha.25 → 2.0.0-alpha.334

package/packages/typescript/src/features/secrets/services/secrets.js

@@ -0,0 +1,566 @@
+/**
+ * Secrets Service
+ *
+ * Core service for multi-level secret management in ElizaOS.
+ * Provides an API for accessing global, world, and user secrets
+ * with encryption, access control, and change notification support.
+ */
+import { resolveSecretKeyAlias, SECRET_KEY_ALIASES, } from "../../../character-utils.js";
+import { logger } from "../../../logger.js";
+import { Service, } from "../../../types/index.js";
+import { KeyManager } from "../crypto/index.js";
+import { CharacterSettingsStorage, ComponentSecretStorage, CompositeSecretStorage, WorldMetadataStorage, } from "../storage/index.js";
+import { MAX_ACCESS_LOG_ENTRIES, SecretsError } from "../types.js";
+import { ValidationStrategies, validateSecret } from "../validation.js";
+/**
+ * Service type identifier
+ */
+export const SECRETS_SERVICE_TYPE = "SECRETS";
+/**
+ * Default service configuration
+ */
+const DEFAULT_CONFIG = {
+    enableEncryption: true,
+    encryptionSalt: undefined,
+    enableAccessLogging: true,
+    maxAccessLogEntries: MAX_ACCESS_LOG_ENTRIES,
+};
+/**
+ * Secrets Service
+ *
+ * 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)
+ */
+export class SecretsService extends Service {
+    static serviceType = SECRETS_SERVICE_TYPE;
+    capabilityDescription = "Manage secrets at global, world, and user levels with encryption and access control";
+    secretsConfig;
+    keyManager;
+    storage;
+    globalStorage;
+    worldStorage;
+    userStorage;
+    accessLogs = [];
+    changeCallbacks = new Map();
+    globalChangeCallbacks = [];
+    mirrorSecretsToProcessEnv = false;
+    constructor(runtime, config) {
+        super(runtime);
+        this.secretsConfig = { ...DEFAULT_CONFIG, ...config };
+        // Initialize encryption key manager
+        this.keyManager = new KeyManager();
+        if (runtime) {
+            this.keyManager.initializeFromAgentId(runtime.agentId, this.secretsConfig.encryptionSalt ??
+                runtime.getSetting("ENCRYPTION_SALT"));
+            // Initialize storage backends
+            this.globalStorage = new CharacterSettingsStorage(runtime, this.keyManager);
+            this.worldStorage = new WorldMetadataStorage(runtime, this.keyManager);
+            this.userStorage = new ComponentSecretStorage(runtime, this.keyManager);
+            // Create composite storage
+            this.storage = new CompositeSecretStorage({
+                globalStorage: this.globalStorage,
+                worldStorage: this.worldStorage,
+                userStorage: this.userStorage,
+            });
+        }
+    }
+    /**
+     * Start the service
+     */
+    static async start(runtime, config) {
+        const service = new SecretsService(runtime, config);
+        await service.initialize();
+        return service;
+    }
+    /**
+     * Initialize the service
+     */
+    async initialize() {
+        logger.info("[SecretsService] Initializing");
+        await this.storage.initialize();
+        // Migrate legacy env vars if needed
+        const migrated = await this.globalStorage.migrateFromEnvVars();
+        if (migrated > 0) {
+            logger.info(`[SecretsService] Migrated ${migrated} legacy env vars`);
+        }
+        // Migrate aliased secret keys to canonical names
+        const aliasesMigrated = await this.migrateAliasedKeys();
+        if (aliasesMigrated > 0) {
+            logger.info(`[SecretsService] Migrated ${aliasesMigrated} aliased keys to canonical names`);
+        }
+        const isSandboxMode = Boolean(this.runtime &&
+            this.runtime.sandboxMode);
+        this.mirrorSecretsToProcessEnv =
+            !isSandboxMode &&
+                ["1", "true", "yes", "on"].includes(String(process.env.ELIZA_ALLOW_SECRET_ENV_SYNC ?? "")
+                    .trim()
+                    .toLowerCase());
+        if (isSandboxMode && this.mirrorSecretsToProcessEnv) {
+            throw new SecretsError("process.env secret mirroring is forbidden in sandbox mode", "PROCESS_ENV_SYNC_FORBIDDEN");
+        }
+        if (this.mirrorSecretsToProcessEnv) {
+            const synced = await this.globalStorage.syncAllToEnv();
+            logger.warn(`[SecretsService] Legacy process.env mirroring enabled; synced ${synced} secrets`);
+        }
+        else {
+            logger.info("[SecretsService] process.env mirroring disabled; callers must read secrets explicitly");
+        }
+        logger.info("[SecretsService] Initialized");
+    }
+    /**
+     * Migrate secrets stored under aliased keys to their canonical names.
+     * This ensures backward compatibility while standardizing key names.
+     */
+    async migrateAliasedKeys() {
+        let migrated = 0;
+        const context = {
+            level: "global",
+            agentId: this.runtime.agentId,
+        };
+        for (const [alias, canonical] of Object.entries(SECRET_KEY_ALIASES)) {
+            // Check if old alias key exists
+            const aliasValue = await this.storage.get(alias, context);
+            if (aliasValue === null) {
+                continue;
+            }
+            // Check if canonical key already exists
+            const canonicalValue = await this.storage.get(canonical, context);
+            if (canonicalValue !== null) {
+                // Canonical already exists, skip (don't overwrite)
+                logger.debug(`[SecretsService] Skipping migration of ${alias} - ${canonical} already exists`);
+                continue;
+            }
+            // Migrate: copy value to canonical key
+            const success = await this.storage.set(canonical, aliasValue, context);
+            if (success) {
+                migrated++;
+                logger.debug(`[SecretsService] Migrated ${alias} to canonical name ${canonical}`);
+            }
+        }
+        return migrated;
+    }
+    /**
+     * Stop the service
+     */
+    async stop() {
+        logger.info("[SecretsService] Stopping");
+        // Clear sensitive data
+        this.keyManager.clear();
+        this.accessLogs = [];
+        this.changeCallbacks.clear();
+        this.globalChangeCallbacks = [];
+        logger.info("[SecretsService] Stopped");
+    }
+    // ============================================================================
+    // Core Secret Operations
+    // ============================================================================
+    /**
+     * Get a secret value.
+     * Automatically resolves aliases to canonical names.
+     */
+    async get(key, context) {
+        // Resolve alias to canonical name
+        const canonicalKey = resolveSecretKeyAlias(key);
+        this.logAccess(canonicalKey, "read", context, true);
+        // Try canonical key first
+        let value = await this.storage.get(canonicalKey, context);
+        // If not found and original key was different, also try the original (for migration)
+        if (value === null && key !== canonicalKey) {
+            value = await this.storage.get(key, context);
+            // If found under old key, migrate to canonical key
+            if (value !== null) {
+                logger.debug(`[SecretsService] Migrating ${key} to canonical name ${canonicalKey}`);
+                await this.storage.set(canonicalKey, value, context);
+                // Optionally delete old key (keeping for backward compatibility for now)
+            }
+        }
+        if (value === null) {
+            this.logAccess(canonicalKey, "read", context, false, "Secret not found");
+        }
+        return value;
+    }
+    /**
+     * Resolve a secret key alias to its canonical name.
+     * Convenience method that delegates to the shared utility.
+     */
+    resolveSecretKey(key) {
+        return resolveSecretKeyAlias(key);
+    }
+    /**
+     * Set a secret value.
+     * Automatically resolves aliases to canonical names.
+     */
+    async set(key, value, context, config) {
+        // Resolve alias to canonical name
+        const canonicalKey = resolveSecretKeyAlias(key);
+        this.logAccess(canonicalKey, "write", context, true);
+        // Validate if validation method specified
+        if (config?.validationMethod && config.validationMethod !== "none") {
+            const validation = await this.validate(canonicalKey, value, config.validationMethod);
+            if (!validation.isValid) {
+                this.logAccess(canonicalKey, "write", context, false, `Validation failed: ${validation.error}`);
+                throw new SecretsError(`Validation failed for ${canonicalKey}: ${validation.error}`, "VALIDATION_FAILED", { key: canonicalKey, error: validation.error });
+            }
+        }
+        // Get previous value for change event
+        const previousValue = await this.storage.get(canonicalKey, context);
+        const success = await this.storage.set(canonicalKey, value, context, config);
+        if (success) {
+            // Sync to process.env if global (using canonical key)
+            if (context.level === "global" && this.mirrorSecretsToProcessEnv) {
+                await this.globalStorage.syncToEnv(canonicalKey);
+            }
+            // Emit change event
+            await this.emitChangeEvent({
+                type: previousValue === null ? "created" : "updated",
+                key: canonicalKey,
+                value,
+                previousValue: previousValue ?? undefined,
+                context,
+                timestamp: Date.now(),
+            });
+        }
+        else {
+            this.logAccess(canonicalKey, "write", context, false, "Storage operation failed");
+        }
+        return success;
+    }
+    /**
+     * Delete a secret.
+     * Automatically resolves aliases to canonical names.
+     */
+    async delete(key, context) {
+        // Resolve alias to canonical name
+        const canonicalKey = resolveSecretKeyAlias(key);
+        this.logAccess(canonicalKey, "delete", context, true);
+        const previousValue = await this.storage.get(canonicalKey, context);
+        const success = await this.storage.delete(canonicalKey, context);
+        if (success) {
+            // Remove from process.env if global (both canonical and original key)
+            if (context.level === "global" && this.mirrorSecretsToProcessEnv) {
+                delete process.env[canonicalKey];
+                if (key !== canonicalKey) {
+                    delete process.env[key];
+                }
+            }
+            // Emit change event
+            await this.emitChangeEvent({
+                type: "deleted",
+                key: canonicalKey,
+                value: null,
+                previousValue: previousValue ?? undefined,
+                context,
+                timestamp: Date.now(),
+            });
+        }
+        else {
+            this.logAccess(canonicalKey, "delete", context, false, "Secret not found");
+        }
+        return success;
+    }
+    /**
+     * Check if a secret exists.
+     * Automatically resolves aliases to canonical names.
+     */
+    async exists(key, context) {
+        const canonicalKey = resolveSecretKeyAlias(key);
+        const exists = await this.storage.exists(canonicalKey, context);
+        // Also check original key for backward compatibility
+        if (!exists && key !== canonicalKey) {
+            return this.storage.exists(key, context);
+        }
+        return exists;
+    }
+    /**
+     * List secrets (metadata only, no values)
+     */
+    async list(context) {
+        return this.storage.list(context);
+    }
+    /**
+     * Get secret configuration
+     */
+    async getConfig(key, context) {
+        return this.storage.getConfig(key, context);
+    }
+    /**
+     * Update secret configuration
+     */
+    async updateConfig(key, context, config) {
+        return this.storage.updateConfig(key, context, config);
+    }
+    // ============================================================================
+    // Convenience Methods
+    // ============================================================================
+    /**
+     * Get a global secret (agent-level)
+     */
+    async getGlobal(key) {
+        return this.get(key, { level: "global", agentId: this.runtime.agentId });
+    }
+    /**
+     * Set a global secret (agent-level)
+     */
+    async setGlobal(key, value, config) {
+        return this.set(key, value, { level: "global", agentId: this.runtime.agentId }, config);
+    }
+    /**
+     * Get a world secret
+     */
+    async getWorld(key, worldId) {
+        return this.get(key, {
+            level: "world",
+            worldId,
+            agentId: this.runtime.agentId,
+        });
+    }
+    /**
+     * Set a world secret
+     */
+    async setWorld(key, value, worldId, config) {
+        return this.set(key, value, { level: "world", worldId, agentId: this.runtime.agentId }, config);
+    }
+    /**
+     * Get a user secret
+     */
+    async getUser(key, userId) {
+        return this.get(key, {
+            level: "user",
+            userId,
+            agentId: this.runtime.agentId,
+            requesterId: userId,
+        });
+    }
+    /**
+     * Set a user secret
+     */
+    async setUser(key, value, userId, config) {
+        return this.set(key, value, {
+            level: "user",
+            userId,
+            agentId: this.runtime.agentId,
+            requesterId: userId,
+        }, config);
+    }
+    // ============================================================================
+    // Validation
+    // ============================================================================
+    /**
+     * Validate a secret value
+     */
+    async validate(key, value, strategy) {
+        return validateSecret(key, value, strategy);
+    }
+    /**
+     * Get available validation strategies
+     */
+    getValidationStrategies() {
+        return Object.keys(ValidationStrategies);
+    }
+    // ============================================================================
+    // Plugin Requirements
+    // ============================================================================
+    /**
+     * Check which secrets are missing for a plugin
+     */
+    async checkPluginRequirements(_pluginId, requirements) {
+        const missingRequired = [];
+        const missingOptional = [];
+        const invalid = [];
+        for (const [key, requirement] of Object.entries(requirements)) {
+            const value = await this.getGlobal(key);
+            if (value === null) {
+                if (requirement.required) {
+                    missingRequired.push(key);
+                }
+                else {
+                    missingOptional.push(key);
+                }
+                continue;
+            }
+            // Validate if validation method specified
+            if (requirement.validationMethod &&
+                requirement.validationMethod !== "none") {
+                const validation = await this.validate(key, value, requirement.validationMethod);
+                if (!validation.isValid) {
+                    invalid.push(key);
+                }
+            }
+        }
+        return {
+            ready: missingRequired.length === 0 && invalid.length === 0,
+            missingRequired,
+            missingOptional,
+            invalid,
+        };
+    }
+    /**
+     * Get missing secrets for a set of keys
+     */
+    async getMissingSecrets(keys, level = "global") {
+        const missing = [];
+        for (const key of keys) {
+            let exists;
+            switch (level) {
+                case "global":
+                    exists = await this.exists(key, {
+                        level: "global",
+                        agentId: this.runtime.agentId,
+                    });
+                    break;
+                case "world":
+                case "user":
+                    // Would need worldId/userId for these
+                    exists = false;
+                    break;
+                default:
+                    exists = false;
+            }
+            if (!exists) {
+                missing.push(key);
+            }
+        }
+        return missing;
+    }
+    // ============================================================================
+    // Change Notifications
+    // ============================================================================
+    /**
+     * Register a callback for changes to a specific secret
+     */
+    onSecretChanged(key, callback) {
+        const callbacks = this.changeCallbacks.get(key) ?? [];
+        callbacks.push(callback);
+        this.changeCallbacks.set(key, callbacks);
+        // Return unsubscribe function
+        return () => {
+            const cbs = this.changeCallbacks.get(key);
+            if (cbs) {
+                const index = cbs.indexOf(callback);
+                if (index !== -1) {
+                    cbs.splice(index, 1);
+                }
+            }
+        };
+    }
+    /**
+     * Register a callback for all secret changes
+     */
+    onAnySecretChanged(callback) {
+        this.globalChangeCallbacks.push(callback);
+        return () => {
+            const index = this.globalChangeCallbacks.indexOf(callback);
+            if (index !== -1) {
+                this.globalChangeCallbacks.splice(index, 1);
+            }
+        };
+    }
+    /**
+     * Emit a change event to registered callbacks
+     */
+    async emitChangeEvent(event) {
+        // Notify key-specific callbacks
+        const keyCallbacks = this.changeCallbacks.get(event.key) ?? [];
+        for (const callback of keyCallbacks) {
+            await callback(event.key, event.value, event.context);
+        }
+        // Notify global callbacks
+        for (const callback of this.globalChangeCallbacks) {
+            await callback(event.key, event.value, event.context);
+        }
+        logger.debug(`[SecretsService] Emitted ${event.type} event for ${event.key}`);
+    }
+    // ============================================================================
+    // Access Logging
+    // ============================================================================
+    /**
+     * Log a secret access attempt
+     */
+    logAccess(key, action, context, success, error) {
+        if (!this.secretsConfig.enableAccessLogging) {
+            return;
+        }
+        const log = {
+            secretKey: key,
+            accessedBy: context.requesterId ?? context.userId ?? context.agentId,
+            action,
+            timestamp: Date.now(),
+            context,
+            success,
+            error,
+        };
+        this.accessLogs.push(log);
+        // Trim logs if over limit
+        if (this.accessLogs.length > this.secretsConfig.maxAccessLogEntries) {
+            this.accessLogs = this.accessLogs.slice(-this.secretsConfig.maxAccessLogEntries);
+        }
+        if (!success && error) {
+            logger.debug(`[SecretsService] Access denied: ${action} ${key} - ${error}`);
+        }
+    }
+    /**
+     * Get access logs
+     */
+    getAccessLogs(filter) {
+        let logs = [...this.accessLogs];
+        if (filter?.key) {
+            logs = logs.filter((l) => l.secretKey === filter.key);
+        }
+        if (filter?.action) {
+            logs = logs.filter((l) => l.action === filter.action);
+        }
+        if (filter?.since) {
+            const since = filter.since;
+            logs = logs.filter((l) => l.timestamp >= since);
+        }
+        if (filter?.context) {
+            logs = logs.filter((l) => {
+                if (filter.context?.level && l.context.level !== filter.context?.level)
+                    return false;
+                if (filter.context?.worldId &&
+                    l.context.worldId !== filter.context?.worldId)
+                    return false;
+                if (filter.context?.userId &&
+                    l.context.userId !== filter.context?.userId)
+                    return false;
+                return true;
+            });
+        }
+        return logs;
+    }
+    /**
+     * Clear access logs
+     */
+    clearAccessLogs() {
+        this.accessLogs = [];
+    }
+    // ============================================================================
+    // Storage Access
+    // ============================================================================
+    /**
+     * Get the global storage backend
+     */
+    getGlobalStorage() {
+        return this.globalStorage;
+    }
+    /**
+     * Get the world storage backend
+     */
+    getWorldStorage() {
+        return this.worldStorage;
+    }
+    /**
+     * Get the user storage backend
+     */
+    getUserStorage() {
+        return this.userStorage;
+    }
+    /**
+     * Get the key manager (for advanced use cases)
+     */
+    getKeyManager() {
+        return this.keyManager;
+    }
+}

package/packages/typescript/src/features/secrets/storage/character-store.d.ts

@@ -0,0 +1,63 @@
+/**
+ * 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).
+ */
+import type { IAgentRuntime } from "../../../types/index.ts";
+import { type KeyManager } from "../crypto/index.ts";
+import type { SecretConfig, SecretContext, SecretMetadata, StorageBackend } from "../types.ts";
+import { BaseSecretStorage } from "./interface.ts";
+/**
+ * Character settings-based storage for global secrets
+ *
+ * Secrets are stored in character.settings.secrets with metadata
+ * tracked separately for configuration management.
+ */
+export 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>;
+}
+//# sourceMappingURL=character-store.d.ts.map

package/packages/typescript/src/features/secrets/storage/character-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"character-store.d.ts","sourceRoot":"","sources":["../../../../../../../../typescript/src/features/secrets/storage/character-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,EAAqB,KAAK,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACxE,OAAO,KAAK,EAEX,YAAY,EACZ,aAAa,EACb,cAAc,EACd,cAAc,EAEd,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAKnD;;;;;GAKG;AACH,qBAAa,wBAAyB,SAAQ,iBAAiB;IAC9D,QAAQ,CAAC,WAAW,EAAE,cAAc,CAAe;IAEnD,OAAO,CAAC,OAAO,CAAgB;IAC/B,OAAO,CAAC,UAAU,CAAa;IAC/B,OAAO,CAAC,WAAW,CAAkB;gBAEzB,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,UAAU;IAMpD,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAcjC;;OAEG;IACH,OAAO,CAAC,uBAAuB;IASzB,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,aAAa,GAAG,OAAO,CAAC,OAAO,CAAC;IAM9D,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAyChE,GAAG,CACR,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,aAAa,EACtB,MAAM,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAC5B,OAAO,CAAC,OAAO,CAAC;IA8Bb,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,aAAa,GAAG,OAAO,CAAC,OAAO,CAAC;IAc9D,IAAI,CAAC,QAAQ,EAAE,aAAa,GAAG,OAAO,CAAC,cAAc,CAAC;IAmCtD,SAAS,CACd,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,aAAa,GACpB,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC;IAgBzB,YAAY,CACjB,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,aAAa,EACvB,MAAM,EAAE,OAAO,CAAC,YAAY,CAAC,GAC3B,OAAO,CAAC,OAAO,CAAC;IAgCnB;;;;;OAKG;IACH,OAAO,CAAC,gBAAgB;IAYxB;;OAEG;IACG,kBAAkB,CAAC,YAAY,GAAE,MAAe,GAAG,OAAO,CAAC,MAAM,CAAC;IAiCxE;;OAEG;IACG,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAItD;;OAEG;IACG,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAWnE;;OAEG;IACG,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC;CAerC"}