hermes-dpapi-secrets

hermes-dpapi-secrets

Resolve Hermes provider keys from a DPAPI-encrypted secret file at startup, instead of
keeping them in plaintext in ~/.hermes/.env or auth.json.

# config.yaml
secrets:
  dpapi:
    enabled: true
    map:
      ZAI_API_KEY: zai
      OPENAI_API_KEY: dpapi://openai

The file holds one blob encrypted with the Windows Data Protection API, keyed by the
current user profile. Hermes decrypts it once per process, applies the mapped values to the
environment with its normal precedence and provenance, and never writes the secret anywhere.

Why this exists

Hermes ships Bitwarden, 1Password and a generic command helper, and the catalog already has
vault backends. None of them answers the small case: one machine, no vault service, and a
provider key that should not sit in a dotfile. On Windows the OS already has the primitive —
DPAPI derives a key from your Windows profile, so a file encrypted with it is readable by
that user on that machine and by nothing else.

The alternative on this platform is hermes-wincred,
which reads individual items from Credential Manager. The difference is where the secret
lives:

| | dpapi (this plugin) | wincred |
|---|---|---|
| Storage | one encrypted file you can back up, move or delete | one Credential Manager item per secret |
| Visible in the Windows UI | no | yes, in Credential Manager → Windows Credentials |
| Size per secret | whatever the file holds | capped by the credential blob (2,560 bytes) |
| Provisioning | python -m hermes_dpapi_secrets set NAME | Credential Manager UI or cmdkey |

Both are DPAPI-backed and user-scoped; pick the one whose storage model you want to live
with. auth.json can then keep an env:ZAI_API_KEY reference rather than the key itself.

Requirements

• Windows 10 or 11.
• Hermes 0.21.4 or newer.
• Nothing else: stdlib only (ctypes), no Python dependencies, no child processes, no
  network calls.

Install

hermes plugins install Yicheng-Mark/hermes-dpapi-secrets
hermes plugins enable hermes-dpapi-secrets

Then add the mapping to config.yaml:

secrets:
  dpapi:
    enabled: true
    file: secrets.dpapi          # optional; relative to the Hermes home
    map:
      ZAI_API_KEY: zai
      OPENAI_API_KEY: dpapi://openai

Creating the store

The runtime side is read-only. Provision the store with the bundled CLI, as the same
Windows user that runs Hermes — the encryption key belongs to that profile:

python -m hermes_dpapi_secrets set ZAI_API_KEY      # prompts; the value is not echoed
printf 'sk-...' | python -m hermes_dpapi_secrets set ZAI_API_KEY   # piped form
python -m hermes_dpapi_secrets list                 # names only, never values
python -m hermes_dpapi_secrets unset ZAI_API_KEY
python -m hermes_dpapi_secrets path                 # where the store lives

--file overrides the store path; by default it is <HERMES_HOME or ~/.hermes>/secrets.dpapi.
Values are never accepted on the command line (where they would reach the shell history and
the process table), never printed, and never written in plaintext.

What it does at startup

For every entry in map, it decrypts the store once and hands the requested values to the
secret-source orchestrator, which applies them like any other source:

• mapped sources beat bulk sources; within a shape, secrets.sources order decides;
• override_existing follows the standard secrets.dpapi config key;
• provenance is reported as (from Windows DPAPI secret file).

A name that is missing from the store, or that holds an empty value, is skipped with a
warning naming it; the other mappings still resolve. If nothing resolves, the source reports
an error and injects nothing. The plugin never writes os.environ, never caches values, and
never calls back into Hermes outside the plugin API.

Security model

• User scope only. Blobs are protected with CRYPTPROTECT_UI_FORBIDDEN and not with
  the machine-wide flag. Machine scope would let any local account on the box decrypt the
  file; that is the wrong default for a secret store, so the option does not exist.
• No prompt on the startup path. CRYPTPROTECT_UI_FORBIDDEN means a locked or
  changed profile fails with an error rather than popping a dialog in a service context.
• Fail closed. A file without this plugin's header, a blob this user cannot decrypt, a
  decrypted payload that is not a flat string map — each is an error, never a partial guess.
• Atomic writes. The CLI writes a temporary file in the same directory and renames it
  into place, so an interrupted write cannot leave a truncated store.

Disclosure

• Decrypts a file for every Hermes process that enables the source. The plaintext lives
  in the process environment of Hermes and its children exactly like a .env entry, for as
  long as the process runs.
• Protects the file at rest, not a running session. DPAPI raises the bar for backups,
  cloud sync, a stolen disk image or a dotfiles repo — the file is useless off this
  machine or to another Windows account. It is not a boundary against code already running
  as you: anything running in your session can call CryptUnprotectData on the same file.
• The CLI writes; the runtime does not. python -m hermes_dpapi_secrets set creates or
  updates the store on explicit user action. The installed plugin's fetch() only reads.
• No network, no subprocesses, no self-update. Updates arrive only through the catalog
  pin and hermes plugins update.

Limitations

• Windows only; on other platforms the source reports BINARY_MISSING and resolves nothing.
• One store per Hermes home. Use file: to point a profile at a different store, or the
  unset/set commands to curate a single one.
• The store is not portable: copying it to another machine or another Windows account makes
  it unreadable by design. Re-create it there instead.
• No caching: the store is read once per process at startup, in-process only.

Development

python -m pytest tests/test_config.py tests/test_store.py -q      # any platform
PYTHONPATH=/path/to/hermes-agent python -m pytest tests -q        # adds the contract suite
PYTHONPATH=/path/to/hermes-agent HERMES_DPAPI_LIVE=1 \
    python -m pytest tests/test_live_dpapi.py -q                  # writes real DPAPI blobs

tests/test_source.py and the live test import agent.secret_sources.base from a Hermes
checkout; tests/test_conformance.py runs the repository's own SecretSourceConformance
kit against this backend. The catalog validator exercises the same contract against the
pinned tree. See VALIDATION.md for the measurements behind the format and
failure-mode choices.

README from the reviewed commit 5bad3fb; it updates when the author re-pins.