tools.manage_secrets module

Per-user secrets management.

Users can store named secrets (passwords, auth tokens, private keys, etc.) encrypted per-user. Other tools can reference secrets by name using the secret:name prefix in credential parameters; the registry resolves these transparently before the handler runs.

Redis key: stargazer:user_secrets:{user_id} Secrets are encrypted at rest (AES-256-GCM) with per-user keys in SQLite.

async tools.manage_secrets.resolve_user_secret(user_id, secret_name, *, redis_client=None, config=None)[source]

Decrypt and return one of a user’s stored secrets, or None if absent.

This is the public read path other tools use to dereference a secret:name credential before their handler runs. It validates the name, reads the ciphertext field from the user’s Redis secrets hash, and decrypts it with the per-user key derived from the master key. Designed to fail soft: any missing secret, unconfigured master key, or decryption error yields None rather than raising, so credential resolution never crashes a caller.

Issues HGET against the hash named by _redis_key() (stargazer:user_secrets:{user_id}) via the supplied Redis client. A legacy plaintext value (failing api_key_encryption.is_encrypted()) is returned as-is. Otherwise it resolves the master key with resolve_master_key(), derives the user key via get_or_create_user_key() (reading the SQLite store at config.api_key_encryption_db_path or _DEFAULT_ENCRYPTION_DB_PATH), and runs the blocking decrypt() in a worker thread. Failures are logged via logger.exception/logger.warning.

Called by _get_secret() in this module and, more importantly, by the secret:name resolution path in tools/__init__.py (which imports SECRET_REF_PREFIX and resolve_user_secret to rewrite credential parameters before dispatching a tool handler).

Parameters:

  • user_id (str) – The platform user whose secret should be read.

  • secret_name (str) – The secret’s name (lowercased before lookup).

  • redis_client – An async Redis client; if falsy the function returns None immediately.

  • config – Optional config object supplying api_key_encryption_db_path.

Returns:

The decrypted secret value, or None if it is missing, the inputs are incomplete, the master key is unset, or decryption fails.

Return type:

str | None