139 lines
4.1 KiB
Markdown
139 lines
4.1 KiB
Markdown
# Secrets Store
|
|
|
|
Centralised key-value store for sensitive tokens and credentials (API keys,
|
|
HuggingFace tokens, etc.) that need to be shared across plugins and tools
|
|
without appearing in `config.yml` or plugin configs.
|
|
|
|
---
|
|
|
|
## Architecture
|
|
|
|
```text
|
|
crates/core-api/src/secrets.rs
|
|
— SecretsApi trait (full CRUD: get, set, delete, list_keys)
|
|
— require() (helper: get or bail with helpful error message)
|
|
|
|
src/secrets.rs
|
|
— SecretsStore (implements SecretsApi over SQLite)
|
|
```
|
|
|
|
`SecretsStore` holds an `Arc<SqlitePool>` and issues direct SQL queries — no
|
|
in-memory cache, no state. It is cheap to clone (just clones the pool Arc).
|
|
|
|
---
|
|
|
|
## Trait API (crates/core-api)
|
|
|
|
```rust
|
|
// core_api::secrets
|
|
#[async_trait]
|
|
pub trait SecretsApi: Send + Sync {
|
|
async fn get(&self, key: &str) -> Option<String>;
|
|
async fn set(&self, key: &str, value: &str) -> Result<()>;
|
|
async fn delete(&self, key: &str) -> Result<()>;
|
|
async fn list_keys(&self) -> Vec<String>; // never returns values
|
|
}
|
|
|
|
// Convenience: returns the value or an anyhow error with instructions.
|
|
pub async fn require(secrets: &Arc<dyn SecretsApi>, key: &str) -> Result<String>;
|
|
```
|
|
|
|
---
|
|
|
|
## Access points
|
|
|
|
| Location | Field | Use |
|
|
|---|---|---|
|
|
| `Skald` | `secrets: Arc<SecretsStore>` | Agent tools, REST API handlers |
|
|
| `PluginContext` | `secrets: Arc<dyn SecretsApi>` | Plugin start/reload (read or write) |
|
|
|
|
Plugins read secrets at startup (e.g. to pass a token to a subprocess). The
|
|
agent writes secrets via its tools. Neither needs to depend on the main crate.
|
|
|
|
---
|
|
|
|
## Usage from a plugin
|
|
|
|
```rust
|
|
use core_api::secrets;
|
|
|
|
// require() fails with a helpful message if the secret is absent.
|
|
let token = secrets::require(&ctx.secrets, "HUGGINGFACE_TOKEN").await?;
|
|
|
|
// Or a soft check:
|
|
if let Some(token) = ctx.secrets.get("MY_API_KEY").await {
|
|
// use token
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Agent tools
|
|
|
|
Two built-in tools let the agent manage secrets without exposing values:
|
|
|
|
| Tool | Parameters | Behaviour |
|
|
|---|---|---|
|
|
| `set_secret` | `key: string`, `value: string\|null` | Sets the secret. Empty string or null **deletes** the key. |
|
|
| `list_secrets` | `pattern?: string` | Returns keys that exist. Optional glob filter (e.g. `GOOGLE_*`). Never returns values. |
|
|
|
|
The agent can check whether a key is set by calling `list_secrets("KEY_NAME")` — if the key is absent from the result it has not been configured yet.
|
|
|
|
## Usage from Rust code
|
|
|
|
Agent tools receive `Arc<dyn SecretsApi>` from `Skald`:
|
|
|
|
```rust
|
|
skald.secrets.set("HUGGINGFACE_TOKEN", &value).await?;
|
|
skald.secrets.delete("OLD_KEY").await?;
|
|
let keys = skald.secrets.list_keys().await; // safe to log
|
|
```
|
|
|
|
---
|
|
|
|
## Well-known keys
|
|
|
|
| Key | Used by |
|
|
|-----|---------|
|
|
| `HUGGINGFACE_TOKEN` | `plugin-tts-orpheus-3b` — passed as `HF_TOKEN` env var to the Python subprocess |
|
|
|
|
Add new rows here when a plugin or tool introduces a new well-known secret key.
|
|
|
|
---
|
|
|
|
## DB: secrets table
|
|
|
|
```sql
|
|
CREATE TABLE secrets (
|
|
key TEXT PRIMARY KEY,
|
|
value TEXT NOT NULL,
|
|
created_at TEXT NOT NULL DEFAULT (datetime('now')),
|
|
updated_at TEXT NOT NULL DEFAULT (datetime('now'))
|
|
)
|
|
```
|
|
|
|
Values are stored in plain text — same protection level as the rest of the
|
|
SQLite database. Do not commit the DB file.
|
|
|
|
---
|
|
|
|
## Security notes
|
|
|
|
- `list_keys()` never returns values — safe to log or surface to the agent.
|
|
- `get()` and `set()` return/accept the raw value — never log these.
|
|
- Keys are case-sensitive uppercase by convention (`HUGGINGFACE_TOKEN`).
|
|
- **The `secrets/` folder is distinct from this store.** Some credentials live on disk under
|
|
a cwd-relative `secrets/` directory (e.g. OAuth tokens written by MCP servers). The
|
|
filesystem read tools (`read_file`, `grep_files`, `list_files`, `search_file`,
|
|
`get_ast_outline`) are **denied** access to `secrets/` via seeded approval rules, so their
|
|
contents never reach the LLM context. See [approval/index.md](approval/index.md). External
|
|
MCP server processes read those token files directly and are unaffected.
|
|
|
|
---
|
|
|
|
## When to Update This File
|
|
|
|
- A new well-known secret key is introduced
|
|
- Access patterns change (new tool, new plugin using secrets)
|
|
- `secrets` table schema changes
|