better-dsh 0.2.5 → 0.3.0

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/secrets/index.md

@@ -1,50 +0,0 @@
-# Secrets
-
-Hermes can pull API keys from external secret managers at process startup instead of storing them in `~/.hermes/.env`. The bootstrap token for the secret manager lives in `.env`; every other provider key (OpenAI, Anthropic, OpenRouter, etc.) can stay in the manager and rotate centrally.
-
-Supported:
-
-- [Bitwarden Secrets Manager](./bitwarden) — `bws` CLI, lazy-installed, free tier works.
-- [1Password](./onepassword) — `op://` references via the official `op` CLI; service-account or desktop session auth.
-- [Command helper](./command) — any CLI vault (`keepassxc-cli`, `secret-tool`, `pass`, custom scripts) via a user-configured helper that prints `KEY=VALUE` lines.
-
-## Multiple sources at once
-
-You can enable more than one secret source at the same time — for example a team Bitwarden project alongside a personal vault plugin. Sources compose per env var with a deterministic precedence ladder:
-
-1. **Your `.env` / shell wins by default.** A source only replaces a pre-existing value when its own `override_existing: true` is set (Bitwarden defaults to true so central rotation works).
-2. **Mapped sources beat bulk sources.** A source where you explicitly bind env vars to references (an `env:` map) outranks a source that injects a whole project of secrets implicitly, regardless of ordering.
-3. **First source wins.** Within the same shape, the order of the optional `secrets.sources` list (or registration order) decides. Later claims on an already-claimed var are skipped — with a startup warning, never silently.
-
-`override_existing` never lets one source overwrite a var another source already claimed, and no source can ever overwrite another source's bootstrap token (e.g. `BWS_ACCESS_TOKEN`).
-
-```yaml
-secrets:
-  sources: [bitwarden]     # optional explicit ordering
-  bitwarden:
-    enabled: true
-    project_id: "..."
-```
-
-Every credential injected by a source is labelled with its origin — setup flows and `hermes model` show `(from Bitwarden)` next to detected keys so you always know where a value came from.
-
-## Profiles and shared vaults
-
-Two orchestrator-level knobs make one shared vault safe across [profiles](../profiles):
-
-- **`secrets.preserve_existing`** — a list of env var names whose existing `.env` / shell value always wins, even against a source with `override_existing: true`. Use it for per-profile platform secrets (e.g. `FEISHU_APP_SECRET`) that intentionally differ across profiles while everything else rotates centrally:
-
-  ```yaml
-  secrets:
-    preserve_existing: [FEISHU_APP_SECRET, TELEGRAM_BOT_TOKEN]
-  ```
-
-- **Profile aliasing** (on by default, `secrets.profile_alias: false` to disable) — when Hermes runs under a named profile, a vault secret named `FOO_<PROFILE>` (credential-shaped suffixes only: `*_API_KEY`, `*_TOKEN`, `*_SECRET`, `*_KEY`, `*_PASSWORD`) also hydrates the canonical `FOO`. Store `TELEGRAM_BOT_TOKEN_MILLA` in the shared project and the `milla` profile's adapters — which read the fixed name `TELEGRAM_BOT_TOKEN` — get the right value automatically. A var the vault supplies directly under its canonical name always beats an alias.
-
-Both apply to every source — bundled and plugin — because they live in the orchestrator, not the backends.
-
-## Adding your own backend
-
-Third-party secret managers ship as standalone plugins, not core PRs. A backend subclasses `agent.secret_sources.base.SecretSource` (one required method: `fetch(cfg, home_path) -> FetchResult`) and registers via `ctx.register_secret_source(MySource())` in the plugin's `register(ctx)`. The orchestrator owns precedence, conflict handling, timeouts, and provenance — your source only fetches. Full guide with the contract rules, subprocess-safety helper, and conformance kit: [Building a Secret Source Plugin](/developer-guide/secret-source-plugin).
-
-The bundled set is deliberately closed (same policy as memory providers): Bitwarden and 1Password ship in-tree. Everything else — Infisical, Proton Pass, HashiCorp Vault, AWS Secrets Manager, OS keystores — belongs in plugin repos; share them in the Nous Research Discord (`#plugins-skills-and-skins`).

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/secrets/onepassword.md

@@ -1,169 +0,0 @@
-# 1Password
-
-Resolve provider API keys from [1Password](https://1password.com/) at process startup instead of storing them in plaintext inside `~/.hermes/.env`. You keep your keys as 1Password items and reference them by `op://vault/item/field`; rotating a credential becomes a single change in 1Password.
-
-## How it works
-
-1. You install the official [1Password CLI](https://developer.1password.com/docs/cli/get-started/) (`op`) and authenticate it — either with a **service-account token** (headless servers) or an **interactive/desktop session** (your laptop).
-2. You map environment-variable names to `op://` references in `~/.hermes/config.yaml`.
-3. Every time `hermes` (or the gateway, or a cron job) starts, after `~/.hermes/.env` has loaded, Hermes runs `op read` for each reference and sets the resolved values into `os.environ`.
-4. By default Hermes **overrides** values already in your environment, so 1Password is the source of truth — rotate a credential once and every Hermes process picks it up on next start. Flip `override_existing: false` if you want `.env` to win instead.
-
-Hermes never authenticates on your behalf and never downloads `op`: it shells out to your already-installed, already-trusted CLI. If `op` is missing, your session is locked, or a reference is wrong, Hermes prints a one-line warning and continues with whatever credentials `.env` already had — it never blocks startup.
-
-## Authentication
-
-`op` supports two non-interactive-friendly modes; Hermes works with either:
-
-- **Service accounts** (recommended for servers/CI): create a service account in 1Password, grant it read access to the relevant vault, and export its token as `OP_SERVICE_ACCOUNT_TOKEN` in `~/.hermes/.env`. The token is the credential — treat it like any other bearer token.
-- **Desktop / interactive sessions** (laptops): run `op signin` (or enable CLI integration in the 1Password app). Hermes passes your `OP_SESSION_*` variables through to the `op` child process. The 1Password cache key includes those session variables, so signing into a different account never serves a value cached under the previous identity.
-
-## Bootstrap token
-
-When you authenticate with a **service-account token**, that token is itself the bootstrap credential Hermes needs *before* it can resolve any `op://` reference. It must be present in `os.environ` of every process that resolves secrets — including cron jobs (`kanban.dispatch_in_gateway: false`), subprocess invocations, CLI runs, macOS launchd agents, and Docker containers — not just the interactive gateway. There are three ways to make it available, in order of precedence:
-
-1. **In `~/.hermes/.env` (recommended).** `hermes secrets onepassword setup --token <token>` writes the token to `~/.hermes/.env`, exactly like Bitwarden's `BWS_ACCESS_TOKEN`. Because `load_hermes_dotenv()` always loads `.env`, the token is available everywhere with zero extra setup. This is the simplest reliable option.
-
-2. **In `~/.hermes/.op.env` (gitignored).** If you'd rather keep the service-account token out of `.env` — for example so `.env` can be checked into a private dotfiles repo while the token stays out of version control — place it in `~/.hermes/.op.env`:
-
-   ```bash
-   echo 'OP_SERVICE_ACCOUNT_TOKEN=ops_...' > ~/.hermes/.op.env
-   chmod 600 ~/.hermes/.op.env
-   ```
-
-   Hermes auto-loads `.op.env` at startup, **after** `.env`, and **never** overrides a token already present in the environment. `.op.env` is gitignored so the token never enters a committed file.
-
-3. **Via systemd `EnvironmentFile` (Linux gateway).** If you run the gateway under systemd, you can inject the token directly into the service environment:
-
-   ```ini
-   [Service]
-   EnvironmentFile=-/home/youruser/.hermes/.op.env
-   ```
-
-   A token injected this way takes precedence — Hermes detects that `OP_SERVICE_ACCOUNT_TOKEN` is already set and skips loading `.op.env` entirely.
-
-If the token is reachable only through an interactive shell (`op signin`, `OP_SESSION_*` exports in `.bashrc`, etc.), it will **not** be inherited by cron jobs or freshly spawned subprocesses, and those contexts will log a warning and fall back to whatever credentials `.env` already held. Use one of the three options above for any non-interactive workload.
-
-## Setup
-
-### 1. Install and sign in to `op`
-
-Follow the [1Password CLI getting-started guide](https://developer.1password.com/docs/cli/get-started/). Verify it works:
-
-```bash
-op whoami
-```
-
-### 2. Enable the integration
-
-```bash
-hermes secrets onepassword setup
-```
-
-This verifies `op` is on `PATH` (or use `--binary-path`), records your account/token settings, checks for an active session, and flips `secrets.onepassword.enabled: true`. Non-interactive flags:
-
-```bash
-hermes secrets onepassword setup \
-  --account my.1password.com \
-  --token-env OP_SERVICE_ACCOUNT_TOKEN \
-  --token "$OP_SERVICE_ACCOUNT_TOKEN"
-```
-
-### 3. Map your credentials
-
-The reference format is `op://<vault>/<item>/<field>`:
-
-```bash
-hermes secrets onepassword set OPENAI_API_KEY    "op://Private/OpenAI/api key"
-hermes secrets onepassword set ANTHROPIC_API_KEY "op://Private/Anthropic/credential"
-```
-
-### 4. Preview and confirm
-
-```bash
-hermes secrets onepassword sync     # dry-run: resolve now, show what would apply
-hermes secrets onepassword status   # config + binary + references + auth
-```
-
-From now on, every `hermes` invocation resolves the references at startup. You'll see a one-line summary in stderr the first time secrets are applied in a process.
-
-## CLI
-
-| Command | What it does |
-|---|---|
-| `hermes secrets onepassword setup` | Verify `op`, set account / token env var, enable |
-| `hermes secrets onepassword status` | Show config, binary, auth, and configured references |
-| `hermes secrets onepassword token` | Rotate the service-account token: validate with `op whoami`, then store it in `.env` |
-| `hermes secrets onepassword set ENV_VAR "op://…"` | Map an env var to a reference (stored stripped + validated) |
-| `hermes secrets onepassword remove ENV_VAR` | Drop a mapping |
-| `hermes secrets onepassword sync` | Dry-run: resolve references now and show what would apply |
-| `hermes secrets onepassword sync --apply` | Resolve and export into the current shell's environment |
-| `hermes secrets onepassword disable` | Flip `enabled: false`; leaves mappings in place |
-
-`op` and `1password` are accepted as aliases for `onepassword`.
-
-## Configuration
-
-Defaults in `~/.hermes/config.yaml`:
-
-```yaml
-secrets:
-  onepassword:
-    enabled: false
-    env:
-      OPENAI_API_KEY: "op://Private/OpenAI/api key"
-      ANTHROPIC_API_KEY: "op://Private/Anthropic/credential"
-    account: ""
-    service_account_token_env: OP_SERVICE_ACCOUNT_TOKEN
-    binary_path: ""
-    cache_ttl_seconds: 300
-    override_existing: true
-```
-
-| Key | Default | What it does |
-|---|---|---|
-| `enabled` | `false` | Master switch. When false, `op` is never invoked. |
-| `env` | `{}` | Mapping of env-var name → `op://vault/item/field` reference. Entries whose name isn't a valid env-var name, or whose value isn't an `op://` reference, are skipped with a warning. |
-| `account` | `""` | Account shorthand / sign-in address passed as `op read --account`. Empty uses `op`'s default account. |
-| `service_account_token_env` | `OP_SERVICE_ACCOUNT_TOKEN` | Env var Hermes reads the service-account token from. Its value is exported to the `op` child as `OP_SERVICE_ACCOUNT_TOKEN` (the name `op` expects). Leave the var unset to use a desktop/interactive session. |
-| `binary_path` | `""` | Absolute path to `op`. When set, it is used verbatim and `PATH` is **not** consulted — pin this to avoid trusting whatever `op` appears first on `PATH`. |
-| `cache_ttl_seconds` | `300` | How long resolved values are reused (in-process and on disk). Set to `0` to disable **both** cache layers — no values are written to disk at all. |
-| `override_existing` | `true` | When true, resolved values overwrite anything already in env (so rotation takes effect). Flip to `false` to let `.env` / shell exports win; those references are then skipped *before* `op` is invoked. |
-
-## Failure modes
-
-1Password never blocks Hermes startup. If anything goes wrong you'll see a one-line warning in stderr and Hermes continues:
-
-| Symptom | Cause | Fix |
-|---|---|---|
-| `the op CLI was not found on PATH` | `op` not installed / not on PATH | Install the CLI, or set `secrets.onepassword.binary_path` |
-| `op read failed for 'op://…': …` | Locked session, expired token, or no vault access | `op signin`, run `hermes secrets onepassword token` to rotate the service-account token, or grant the service account access |
-| `op read returned an empty value for 'op://…'` | The referenced field exists but is empty | Fix the item/field in 1Password (an empty value is never applied — your existing env var is left intact) |
-| `… is not an op:// secret reference` | A mapping value isn't an `op://` reference | Re-set it with the correct `op://vault/item/field` form |
-| `op read timed out` | Network blocked or 1Password slow | Check connectivity / the desktop app integration |
-
-Startup warnings now include a `→` remediation line telling you exactly which command fixes the failure.
-
-## Caching
-
-Successful, complete pulls are cached in-process and on disk under `<hermes_home>/cache/op_cache.json` (written atomically, mode `0600`), so back-to-back short-lived `hermes` invocations don't re-shell `op` for every reference. The cache:
-
-- stores only resolved secret **values** — never the service-account token or any raw auth material (auth is fingerprinted into the cache key);
-- is invalidated when the token, account, `OP_SESSION_*` variables, or the set of references change;
-- is **not** written when a pull had any per-reference error, so a transient auth failure isn't frozen in for the TTL;
-- is fully disabled — reads *and* writes — when `cache_ttl_seconds: 0`.
-
-## Security notes
-
-- A 1Password service-account token can read every secret the account has access to. Store it in `~/.hermes/.env` (not `config.yaml`), and revoke + regenerate from 1Password if it leaks.
-- Hermes refuses to let a resolved value overwrite the token env var itself, even with `override_existing: true`.
-- The `op` child process gets a minimal allowlisted environment (auth/session vars + `PATH`/`HOME` and the `op` config-location vars `OP_CONFIG_DIR`/`XDG_CONFIG_HOME`), not a copy of the full `os.environ`, so post-dotenv provider credentials aren't all inherited by the child. Set `OP_CONFIG_DIR` when `~/.config` is not writable by the Hermes user (common in containers).
-- References are validated to start with `op://`, and the reference is passed after a `--` option terminator so a crafted value can't be parsed as an `op` flag.
-
-## When NOT to use this
-
-- **Single-machine personal setups** where `~/.hermes/.env` is fine.
-- **Air-gapped environments** that can't reach 1Password.
-- **CI/CD** where an existing secrets-injection mechanism is already wired up — pick one path, not two.
-
-The good case for this is multi-machine fleets, shared dev boxes, gateway VPSes, or anywhere you want centralized rotation and revocation across multiple Hermes installations.